docs: exhaustive dedupe, compaction, OKF conformance, fact verification #30
@@ -100,15 +100,18 @@ secret in every agent's context window on every machine that pulls this repo.
|
||||
|
||||
| box | role | GPU | notes |
|
||||
|-----|------|-----|-------|
|
||||
| Dev workstation | client box, never runs inference | laptop iGPU + dGPU (non-unified) | mainline llama.cpp at `~/GitPackages/llama.cpp/build/bin/`; this repo lives here at `~/.omp` |
|
||||
| Dev workstation (`blankpad`) | client box, never runs inference | Lenovo laptop, AMD Ryzen 5 PRO 5650U / Cezanne APU (**unified memory**, s2idle sleep only, no dGPU) | this repo lives here at `~/.omp`; the earlier "iGPU + dGPU / `~/GitPackages/llama.cpp`" description belonged to the sold `dankware` box |
|
||||
| Dankclaw | bench target, secondary models + service stack | Strix Halo APU (**unified memory**) + RTX 3090 (moved over from Dankserver 2026-09) | prod services `frank-dragoon` (halogen-flash-server, :7770, iGPU) and `frank-zealot` (llama.cpp PrismML fork, :7771, 3090); runbooks in the serverAppConfigs vault (`~/Projects/serverAppConfig/serverAppConfigs-docs/LLM/`); ssh: `ssh dankclaw` |
|
||||
| Dankserver | main-model box | 2× Radeon AI PRO R9700 — non-unified (was RTX 3090 until 2026-09) | runs `frank-archon` (radiance, TP=2, :7770) — **this repo's operator session runs on it**; ssh: `ssh dankserver` |
|
||||
|
||||
## Environment gotchas
|
||||
|
||||
- Gitea API needs a token: `GITEA_TOKEN` env (gitignored `.env`). No `tea` CLI
|
||||
installed anywhere. Remote URLs embed the token locally in `.git/config` — that
|
||||
file is never pushed; it is not a substitute for the secret gate.
|
||||
installed anywhere. Remote URLs carry NO embedded token (2026-10-09
|
||||
credential-store cutover) — git and the API both read
|
||||
`~/.config/secrets/gitea` (`store --file`, URL-line format; see
|
||||
`omp-docs/tools/gitea/client-access.md`). That file is never pushed; it is
|
||||
not a substitute for the secret gate.
|
||||
- Passwordless sudo (`sudo -n`) works on Dankclaw and Dankserver for systemctl
|
||||
verbs only; user units need no sudo at all.
|
||||
- SSH into both servers is BatchMode-capable from here:
|
||||
|
||||
@@ -2,7 +2,12 @@
|
||||
|
||||
Agentic web research means that an AI drives the search loop. The agent formulates queries, reads results, decides what to read next, and writes a synthesis. It works best when search, extraction, and reasoning each run in the right place.
|
||||
|
||||
> **Your setup:** Pi Web Access calls SearXNG at `192.168.0.143:8081` (dankclaw) and serves models through llama.cpp at `192.168.0.235:7770`, `192.168.0.143:7770`, and `localhost:8080`. The pages below assume that topology.
|
||||
> **Fleet topology (2026-10):** SearXNG lives at `192.168.0.143:8081` (UI) /
|
||||
> `:8082` (JSON) on dankclaw; model endpoints are `frank-archon`
|
||||
> (dankserver :7770, radiance), `frank-dragoon` (dankclaw :7770,
|
||||
> halogen-flash-server), `frank-zealot` (dankclaw :7771, llama.cpp PrismML).
|
||||
> The pi-era `localhost:8080` llama.cpp endpoint is retired. See
|
||||
> [System hosts](/system/index.md).
|
||||
|
||||
This section connects four decisions:
|
||||
|
||||
|
||||
@@ -32,9 +32,15 @@ Qwen3 is the current state of the art for open function calling and tool use. It
|
||||
|
||||
The 8B and 14B models run on one consumer GPU. The 30B-A3B MoE runs on a single A100-class card or equivalent.
|
||||
|
||||
## Best Vision Model: Qwen2.5-VL-7B
|
||||
## Best Vision Model: Qwen3-VL (Apache 2.0)
|
||||
|
||||
Many web tasks need a model that can read a page image, not just text. Qwen2.5-VL-7B is the best open vision model for this. It reads text, charts, icons, and layout in screenshots. It supports computer-use and phone-use agents. Apache 2.0 license. The 7B model fits on a single GPU with 8 GB or more.
|
||||
Many web tasks need a model that can read a page image, not just text.
|
||||
**Qwen3-VL** supersedes Qwen2.5-VL as the strongest open-weights vision family
|
||||
(4B/8B dense through 30B-A3B/235B-A22B MoE): text, chart, icon, and layout
|
||||
reading in screenshots, plus computer-use agent support. Small dense sizes
|
||||
ship Apache 2.0; a quantized 4B/8B runs on a single consumer GPU. On this
|
||||
fleet, vision duty is carried by the mmproj vision towers on the endpoints
|
||||
(dragoon, zealot) — see [System hosts](/system/index.md).
|
||||
|
||||
Llama 4 Scout is the larger multimodal option. Verify the claims before you trust them:
|
||||
|
||||
@@ -47,7 +53,7 @@ Llama 4 Scout is the larger multimodal option. Verify the claims before you trus
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Consumer GPU 16-24GB] --> B[Qwen3-8B / 14B]
|
||||
A --> C[Qwen2.5-VL-7B]
|
||||
A --> C[Qwen3-VL-4B / 8B]
|
||||
D[Single server GPU 80GB] --> E[Qwen3-30B-A3B]
|
||||
D --> F[Llama 4 Scout INT4]
|
||||
G[Multi-GPU cluster] --> H[Qwen3-235B-A22B]
|
||||
@@ -71,7 +77,7 @@ llama-server -m qwen3-8b-q4_k_m.gguf -c 131072 --port 7770
|
||||
| Need | Pick |
|
||||
|------|------|
|
||||
| Best tool calling, one consumer GPU | Qwen3-8B or 14B |
|
||||
| Visually read a web page | Qwen2.5-VL-7B |
|
||||
| Visually read a web page | Qwen3-VL-4B / 8B |
|
||||
| Server-scale reliable agent | Qwen3-235B-A22B |
|
||||
| Cheapest acceptable agent | Qwen3-8B on a mid GPU |
|
||||
|
||||
@@ -79,7 +85,8 @@ llama-server -m qwen3-8b-q4_k_m.gguf -c 131072 --port 7770
|
||||
|
||||
- Qwen3 technical report: <https://qwenlm.github.io/blog/qwen3/>
|
||||
- Qwen3 repository: <https://github.com/QwenLM/Qwen3>
|
||||
- Qwen2.5-VL-7B model card: <https://huggingface.co/Qwen/Qwen2.5-VL-7B-Instruct>
|
||||
- Qwen3-VL repository: <https://github.com/QwenLM/Qwen3-VL> (tech report: <https://arxiv.org/abs/2511.21631>)
|
||||
- Qwen2.5-VL-7B model card (predecessor): <https://huggingface.co/Qwen/Qwen2.5-VL-7B-Instruct>
|
||||
- Meta AI Llama 4 announcement: <https://ai.meta.com/blog/llama-4-multimodal-intelligence/>
|
||||
- Ollama library: <https://ollama.com/library>
|
||||
- Browser Use supported models: <https://docs.browser-use.com/open-source/supported-models>
|
||||
|
||||
@@ -8,18 +8,41 @@ tags:
|
||||
- privacy
|
||||
- configuration
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
verified: 2026-10-19
|
||||
timestamp: 2026-08-11
|
||||
resource: https://docs.searxng.org
|
||||
---
|
||||
|
||||
# SearXNG Tuning
|
||||
|
||||
SearXNG is a metasearch engine. It aggregates 274 or more upstream search services into one result set. Configuration lives in `settings.yml`. The recommended deployment is Docker Compose with a Valkey container.
|
||||
SearXNG is a metasearch engine. It aggregates hundreds of upstream search
|
||||
services into one result set (upstream `settings.yml` defines 388 engine
|
||||
entries at master, probed 2026-10-19; the live fleet instance loads 262).
|
||||
Configuration lives in `settings.yml`. The recommended deployment is Docker
|
||||
Compose (or Podman Quadlet) with a Valkey container.
|
||||
|
||||
This page lists the settings that matter for speed, privacy, and useful results.
|
||||
|
||||
> **Your setup:** Pi Web Access calls a remote SearXNG at [`192.168.0.143:8081`](../pi/packages/pi-web-access.md) (dankclaw). Apply these settings to that host, not to this machine.
|
||||
> **Fleet instance:** the harness `web/searxng` provider calls the instance at
|
||||
> `192.168.0.143:8081` (UI) / `:8082` (JSON API) on dankclaw. The pi-era
|
||||
> [Pi Web Access](../pi/packages/pi-web-access.md) called the same host.
|
||||
|
||||
## Live instance (probed 2026-10-19)
|
||||
|
||||
User Quadlet stack on dankclaw: `searxng.container`
|
||||
(`ghcr.io/searxng/searxng:latest`) + `searxng-valkey.container`
|
||||
(`docker.io/valkey/valkey:9-alpine`) + `gluetun.container` (VPN egress; the
|
||||
containers share its network namespace, which is why `podman ps` shows :8081/
|
||||
:8082 on several names) + `marreta`/`marreta_browser`. `limiter.toml`: enabled,
|
||||
`pass_searxng_org: true`.
|
||||
|
||||
**Policy drift flag:** this page's tuned engine policy (google and bing
|
||||
disabled; DuckDuckGo/Wikipedia/Google News enabled — verified via `/config` on
|
||||
2026-08-16) is NOT live: `/config` on 2026-10-19 reports all 262 engines
|
||||
enabled, google and bing included. Either the settings override was lost in
|
||||
the 2026-10 stack reinstatement or the policy was deliberately dropped.
|
||||
Confirm with Frank before re-applying.
|
||||
|
||||
|
||||
## Plan the Deployment
|
||||
|
||||
|
||||
@@ -29,10 +29,17 @@ Key ideas:
|
||||
- Ten watchdogs handle CAPTCHAs, crashes, popups, downloads, and security.
|
||||
- Real browser profiles carry saved logins.
|
||||
|
||||
**On the "87.4 percent" number:** that result refers to Browser Use's managed Cloud agent (the Hybrid type that blends structured browser tools with screenshots). Peer-reviewed results for vision-only (CUA) models are much lower, about 44.5 percent on the same task type. Treat any single accuracy number as one benchmark, not a universal score.
|
||||
**On the "87.4 percent" number:** that result refers to Browser Use's managed
|
||||
Cloud agent (the Hybrid type that blends structured browser tools with
|
||||
screenshots), not the open-source library you self-host. Academic
|
||||
computer-use results on comparable web tasks run far lower, and an earlier
|
||||
"44.5 percent peer-reviewed CUA" figure carried in this page could not be
|
||||
re-attributed to a specific published benchmark (checked 2026-10-19) and was
|
||||
dropped. Treat any single accuracy number as one benchmark, not a universal
|
||||
score.
|
||||
|
||||
```python
|
||||
# Local model via llama.cpp (OpenAI-compatible endpoint)
|
||||
# Local model via any OpenAI-compatible endpoint
|
||||
from browser_use import Agent
|
||||
from browser_use.llm.openai import ChatOpenAI
|
||||
|
||||
@@ -40,7 +47,7 @@ agent = Agent(
|
||||
task="Search for the latest AI news",
|
||||
llm=ChatOpenAI(
|
||||
base_url="http://192.168.0.235:7770/v1",
|
||||
model="frank-default-small",
|
||||
model="frank-archon",
|
||||
api_key="EMPTY",
|
||||
),
|
||||
)
|
||||
|
||||
@@ -171,8 +171,14 @@ This pattern places the whole SearXNG process inside the tunnel namespace. The h
|
||||
4. Confirm that unrelated host traffic keeps the host IP.
|
||||
|
||||
```bash
|
||||
# From inside the tunnel with Gluetun
|
||||
docker exec gluetun curl -s ifconfig.me
|
||||
# Gluetun ships no curl; use its own endpoints or a throwaway container.
|
||||
podman exec gluetun sh -c 'test -e /sys/class/net/tun0 && echo tunnel-up'
|
||||
podman exec gluetun sh -c 'wget -qO- 127.0.0.1:9999/health' # "OK" when up
|
||||
# NOTE: :9999 is Gluetun's HTTP health server (200 "OK" / 500); :8000 is the
|
||||
# CONTROL server (/v1/* API), which 404s on everything else. Do not health-
|
||||
# probe :8000. Egress-IP check needs a real binary — run a companion
|
||||
# container on gluetun's network: docker run --rm --net container:gluetun
|
||||
# curlimages/curl -s ifconfig.me
|
||||
```
|
||||
|
||||
## Citations
|
||||
|
||||
@@ -2,14 +2,13 @@
|
||||
|
||||
Caddy is the reverse proxy and TLS terminator for the homelab. A single caddy
|
||||
container on dankclaw (192.168.0.143) fronts every service on both hosts. It
|
||||
runs Caddy v2.11.4 from the custom `franksdank/caddy-porkbun` image
|
||||
(xcaddy-built with the Porkbun DNS-01 module, built locally on dankclaw).
|
||||
runs Caddy v2.11.7 (verified in-container 2026-10-19) from the custom
|
||||
`localhost/franksdank/caddy-porkbun:latest` image (xcaddy-built with the
|
||||
Porkbun DNS-01 module, built locally on dankclaw).
|
||||
Since 2026-08-26 it is managed as a Podman Quadlet unit (`caddy.container`)
|
||||
installed to `~/.config/containers/systemd/`, providing boot-persistent,
|
||||
auto-restart service management.
|
||||
|
||||
* [[caddyfile|caddyfile]] — directive and matcher syntax, named matchers,
|
||||
directive sorting, and the `handle`/`route` order rule.
|
||||
|
||||
The Caddyfile lives in the serverAppConfigs repo at
|
||||
`dankclaw/Caddyfile`. `deploy.sh` renders basicauth hashes from the host `.env`
|
||||
@@ -27,4 +26,4 @@ resolves `*.franksdank.cloud` names to dankclaw.
|
||||
|
||||
The porkbun DNS module source: [caddy-dns/porkbun](https://github.com/caddy-dns/porkbun).
|
||||
|
||||
* [Caddyfile Syntax](caddyfile.md) — Caddy Caddyfile reference — directive and matcher syntax, named matchers, directive sorting, and the handle/route order rule. Grounded in caddyserver.com (fetched 2026-08-28).
|
||||
* [Caddyfile Syntax](caddyfile.md) — Caddy Caddyfile reference — directive and matcher syntax, named matchers, directive sorting, and the `handle`/`route` order rule. Grounded in caddyserver.com (fetched 2026-08-28).
|
||||
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: AGENTS.md Index
|
||||
description: Overview of the cached tool documentation system — how it works, why the pre-flight check matters, and how to add new entries.
|
||||
tags:
|
||||
- documentation
|
||||
- index
|
||||
- pre-flight-check
|
||||
- meta
|
||||
timestamp: 2026-01-15
|
||||
---
|
||||
|
||||
# pi Documentation Index
|
||||
|
||||
This directory (`/home/dank/.pi/agent/docs/`) contains cached documentation for tools used during system configuration. It is the agent's primary reference before touching any configuration file.
|
||||
|
||||
---
|
||||
|
||||
## How to Use
|
||||
|
||||
Before configuring any tool, check whether documentation already exists here. If it does not, a subagent **must** be spawned to fetch documentation before proceeding.
|
||||
|
||||
This is not a suggestion. It is the difference between "I remember how to configure this" and "I will need to re-read the docs for the third time this week."
|
||||
|
||||
---
|
||||
|
||||
## Available Tool Documentation
|
||||
|
||||
### Core
|
||||
|
||||
* [AGENTS.md Format](agents-md-format.md) — Structure specification for the system-level instruction file: layer conventions, naming, summary table format, and add/remove procedures.
|
||||
|
||||
### Tools
|
||||
|
||||
* [Ghostty Terminal](../tools/ghostty/index.md) — GPU-accelerated terminal emulator. Complete configuration reference with 100+ options organized by category, CLI actions, keybindings, shaders, and default bindings.
|
||||
* [llama.cpp Server](../tools/llama-cpp/index.md) — LLM inference server. GGUF format, build guides (CPU/CUDA/Metal/Vulkan), server CLI options, API endpoints, Docker setup, and curl examples.
|
||||
* [Linux Power Management](../tools/linux-power-management.md) — Systemd sleep configuration, kernel sleep states, NVIDIA GPU suspend/resume, diagnostic tools, kernel parameters, and automated testing procedures.
|
||||
* [Niri](../tools/niri/index.md) — Scrollable-tiling Wayland compositor. Full keybind cheat sheet, configuration syntax, window management, workspace navigation, and action reference.
|
||||
|
||||
### Pi Packages
|
||||
|
||||
* [pi-browser-use](../packages/pi-browser-use.md) — Browser automation extension wrapping chrome-devtools-mcp with `browser_` prefix, full config reference, session modes, vision model setup, and tool augmentation docs.
|
||||
* [pi-permission-system](../packages/pi-permission-system.md) — 10 docs covering permission enforcement, config reference, session approvals, cross-extension API, subagent integration, troubleshooting, and migration guides.
|
||||
|
||||
### Skills
|
||||
|
||||
* [Npx Skills](../skills/npx-skills.md) — Distribution and installation patterns for agent skills via npm, package structure, SKILL.md frontmatter, discovery rules, and the Agent Skills specification.
|
||||
* [Vercel Labs `skills` CLI](../skills/vercel-skills.md) — CLI meta-installer for cross-agent skill distribution, supporting 68+ agents, with add/use/find/list/update/remove commands.
|
||||
|
||||
### References
|
||||
|
||||
* [OKF v0.1 Specification](../references/okf-spec.md) — Complete specification for OKF knowledge bundles: bundle structure, frontmatter fields, concept documents, index/log files, cross-linking, and conformance rules.
|
||||
* [OKF Bundle Maintenance](../references/okf-maintenance.md) — Bundle maintenance: log.md format, frontmatter discipline, one-concept-per-file, staleness detection, and automation strategies.
|
||||
|
||||
---
|
||||
|
||||
## Adding New Tool Documentation
|
||||
|
||||
When a subagent fetches documentation for a new tool:
|
||||
|
||||
1. Save it to `tools/<tool-name>/index.md` (multi-file) or `tools/<tool-name>.md` (small, single-concept).
|
||||
2. Add an entry to this index table.
|
||||
3. Include a brief description of what the document covers.
|
||||
4. Add YAML frontmatter with `type` and `description`.
|
||||
5. Update `log.md` with the change.
|
||||
|
||||
---
|
||||
|
||||
## Index Format
|
||||
|
||||
Give each row this content:
|
||||
|
||||
- **Tool** — the tool or technology name
|
||||
- **File / Path** — relative path within this directory
|
||||
- **Status** — for example, "Complete", "Partial", "Needs Update"
|
||||
@@ -11,9 +11,10 @@ These files define the structural conventions that govern the agent system itsel
|
||||
## Concept Files
|
||||
|
||||
* [AGENTS.md Format Specification](agents-md-format.md) — Canonical structure and conventions for the system-level instruction file that governs agent behavior.
|
||||
* [AGENTS.md Index](index-doc.md) — Overview of the cached tool documentation system and how to add new entries.
|
||||
* [Pi Settings System](settings.md) — pi-era `settings.json` record (archive): providers, models, packages, subagent overrides.
|
||||
* [dankvoice](dankvoice.md) — Cloned-voice vocalization extension: `/say` and auto-speak over frank-tts, endpoint read from `agent/models.yml`.
|
||||
* [OMP Status Line Customization](statusline.md) — How presets, composer shapes, and segment arrays actually interact; the fleet's tuned bar. (moved from /pi/, 2026-10-19)
|
||||
* [OMP Subagent Limits & Fan-out Policy](subagent-limits.md) — Live caps: concurrency 2, no nested spawns (the `maxRecursionDepth: 0` trap), per-endpoint in-flight ceilings, isolation policy. (moved from /pi/, 2026-10-19)
|
||||
|
||||
## Change Tracking
|
||||
|
||||
|
||||
@@ -222,7 +222,7 @@ Currently installed:
|
||||
| `@xynogen/pix-ls` | 0.2.1 | Directory listing |
|
||||
| `@xynogen/pix-edit` | 0.2.1 | File editing utilities |
|
||||
|
||||
See [packages](../packages/index.md) for full package documentation.
|
||||
See [Pi Packages](/pi/packages/index.md) for full package documentation.
|
||||
|
||||
---
|
||||
|
||||
@@ -236,5 +236,5 @@ When `lastChangelogVersion` is behind pi's internal version, pi prompts for migr
|
||||
|
||||
- [pi](../pi/index.md) — Pi configuration overview
|
||||
- [[models|models]] — Provider and model definitions
|
||||
- [packages](../packages/index.md) — Installed package documentation
|
||||
- [Pi Packages](/pi/packages/index.md) — Installed package documentation
|
||||
- [[skills|skills]] — Installed skill documentation
|
||||
|
||||
@@ -92,6 +92,6 @@ just the setting description.
|
||||
|
||||
# See Also
|
||||
|
||||
- [/pi/statusline.md](/pi/statusline.md) — the omp-era bundle-audit page pattern this page follows
|
||||
- [/core/statusline.md](/core/statusline.md) — the omp-era bundle-audit page pattern this page follows
|
||||
- [/pi/packages/pi-subagents.md](/pi/packages/pi-subagents.md) — retired pi-era subagent system (historical)
|
||||
- [/system/index.md](/system/index.md) — fleet endpoints these ceilings target
|
||||
@@ -97,4 +97,4 @@ Distribute skills through npm packages with a `pi` manifest, or through the `ski
|
||||
## See Also
|
||||
|
||||
* [SDLC and Tooling](sdlc.md)
|
||||
* [Skills Ecosystem](skills-ecosystem.md)
|
||||
* [Skills Ecosystem](/skills/ecosystem.md)
|
||||
|
||||
@@ -11,7 +11,7 @@ This area distills grounded research into an OKF knowledge bundle. Each page cov
|
||||
* [Language and Framework Stacks](languages/index.md) - Node/JavaScript, React, Python, Rust, Go.
|
||||
* [Infrastructure and Cloud](infra/index.md) - Terraform/OpenTofu, containers, Kubernetes, AWS, DigitalOcean, Hetzner.
|
||||
* [Pi Plugins](plugins.md) - The pi extension ecosystem and notable packages.
|
||||
* [Skills Ecosystem](skills-ecosystem.md) - skills.sh registry and the top skills.
|
||||
* [Skills Ecosystem](/skills/ecosystem.md) - skills.sh registry and the live install leaderboard.
|
||||
* [Signal Remote Control](signal-remote.md) - Drive a pi instance from Signal messages.
|
||||
|
||||
## Conventions
|
||||
|
||||
@@ -38,7 +38,7 @@ Some package names that appear in older documentation, such as `pi-browser-use`
|
||||
|
||||
## Related Ecosystem
|
||||
|
||||
Pi implements the open Agent Skills standard. This makes pi skills compatible with Claude Code, Codex CLI, Amp, Droid, Cursor, and many other agents. See the [Skills Ecosystem](skills-ecosystem.md) page.
|
||||
Pi implements the open Agent Skills standard. This makes pi skills compatible with Claude Code, Codex CLI, Amp, Droid, Cursor, and many other agents. See the [Skills Ecosystem](/skills/ecosystem.md) page.
|
||||
|
||||
## Citations
|
||||
|
||||
|
||||
@@ -1,144 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills Ecosystem and Top Skills
|
||||
description: The skills.sh registry, the Agent Skills ecosystem, and the verified top 50 skills by installs.
|
||||
tags:
|
||||
- skills
|
||||
- skills-sh
|
||||
- agent-skills
|
||||
- ecosystem
|
||||
- engineering
|
||||
- unverified
|
||||
---
|
||||
verified: 2026-08-28
|
||||
|
||||
# Skills Ecosystem and Top Skills
|
||||
|
||||
This page covers the open agent skills ecosystem. It describes the registries, the install tooling, and the top skills by category.
|
||||
|
||||
## The Ecosystem
|
||||
|
||||
`skills.sh` is the primary registry and leaderboard for agent skills. It runs on the open-source `skills` CLI from Vercel Labs. Use these commands:
|
||||
|
||||
```bash
|
||||
npx skills add <owner/repo> # Install skills
|
||||
npx skills find [query] # Search skills
|
||||
npx skills list # List installed skills
|
||||
```
|
||||
|
||||
The underlying standard is the Agent Skills specification at [agentskills.io](https://agentskills.io). Over 20 coding agents support it. A single `SKILL.md` works across these agents.
|
||||
|
||||
Related registries:
|
||||
|
||||
| Registry | Focus |
|
||||
|----------|-------|
|
||||
| skills.sh | Primary registry and leaderboard. |
|
||||
| agentskill.sh | Directory and marketplace with many indexed skills. |
|
||||
| officialskills.sh | Verified skills from major organizations. |
|
||||
| qaskills.sh | QA and testing skills. |
|
||||
|
||||
Use the local `npx skills` command to explore what is available. You can query the leaderboard data directly at `GET /api/skills/all-time/{page}` on skills.sh. The page index is zero-based and returns 200 skills per page.
|
||||
|
||||
## Top 50 Skills by All-Time Installs
|
||||
|
||||
The table lists the top 50 skills verified from the live skills.sh API on 2026-08-12. Install counts are exact at query time.
|
||||
|
||||
| # | Skill | Source | Installs |
|
||||
|----|-------|--------|----------|
|
||||
| 1 | `find-skills` | vercel-labs/skills | 2,918,155 |
|
||||
| 2 | `grill-me` | mattpocock/skills | 832,797 |
|
||||
| 3 | `frontend-design` | anthropics/skills | 767,871 |
|
||||
| 4 | `grill-with-docs` | mattpocock/skills | 708,703 |
|
||||
| 5 | `improve-codebase-architecture` | mattpocock/skills | 683,652 |
|
||||
| 6 | `tdd` | mattpocock/skills | 660,660 |
|
||||
| 7 | `agent-browser` | vercel-labs/agent-browser | 659,465 |
|
||||
| 8 | `vercel-react-best-practices` | vercel-labs/agent-skills | 625,739 |
|
||||
| 9 | `setup-matt-pocock-skills` | mattpocock/skills | 607,703 |
|
||||
| 10 | `handoff` | mattpocock/skills | 570,592 |
|
||||
| 11 | `triage` | mattpocock/skills | 568,784 |
|
||||
| 12 | `lark-doc` | open.feishu.cn | 561,794 |
|
||||
| 13 | `lark-approval` | open.feishu.cn | 561,758 |
|
||||
| 14 | `lark-base` | open.feishu.cn | 561,634 |
|
||||
| 15 | `lark-drive` | open.feishu.cn | 561,452 |
|
||||
| 16 | `lark-shared` | open.feishu.cn | 561,337 |
|
||||
| 17 | `lark-calendar` | open.feishu.cn | 561,273 |
|
||||
| 18 | `lark-im` | open.feishu.cn | 561,248 |
|
||||
| 19 | `lark-contact` | open.feishu.cn | 561,157 |
|
||||
| 20 | `lark-sheets` | open.feishu.cn | 561,006 |
|
||||
| 21 | `lark-wiki` | open.feishu.cn | 560,924 |
|
||||
| 22 | `lark-attendance` | open.feishu.cn | 560,891 |
|
||||
| 23 | `lark-event` | open.feishu.cn | 560,888 |
|
||||
| 24 | `lark-minutes` | open.feishu.cn | 560,818 |
|
||||
| 25 | `lark-openapi-explorer` | open.feishu.cn | 560,777 |
|
||||
| 26 | `lark-whiteboard` | open.feishu.cn | 560,768 |
|
||||
| 27 | `lark-mail` | open.feishu.cn | 560,720 |
|
||||
| 28 | `lark-task` | open.feishu.cn | 560,692 |
|
||||
| 29 | `lark-slides` | open.feishu.cn | 560,590 |
|
||||
| 30 | `lark-skill-maker` | open.feishu.cn | 560,554 |
|
||||
| 31 | `lark-vc` | open.feishu.cn | 560,466 |
|
||||
| 32 | `lark-workflow-meeting-summary` | open.feishu.cn | 560,368 |
|
||||
| 33 | `lark-workflow-standup-report` | open.feishu.cn | 560,358 |
|
||||
| 34 | `prototype` | mattpocock/skills | 556,403 |
|
||||
| 35 | `lark-okr` | open.feishu.cn | 541,430 |
|
||||
| 36 | `web-design-guidelines` | vercel-labs/agent-skills | 535,426 |
|
||||
| 37 | `lark-markdown` | open.feishu.cn | 526,555 |
|
||||
| 38 | `microsoft-foundry` | microsoft/azure-skills | 523,287 |
|
||||
| 39 | `azure-diagnostics` | microsoft/azure-skills | 518,052 |
|
||||
| 40 | `azure-ai` | microsoft/azure-skills | 517,867 |
|
||||
| 41 | `azure-deploy` | microsoft/azure-skills | 517,694 |
|
||||
| 42 | `azure-prepare` | microsoft/azure-skills | 517,512 |
|
||||
| 43 | `azure-validate` | microsoft/azure-skills | 517,228 |
|
||||
| 44 | `azure-storage` | microsoft/azure-skills | 516,821 |
|
||||
| 45 | `entra-app-registration` | microsoft/azure-skills | 516,567 |
|
||||
| 46 | `appinsights-instrumentation` | microsoft/azure-skills | 516,335 |
|
||||
| 47 | `azure-resource-lookup` | microsoft/azure-skills | 516,249 |
|
||||
| 48 | `azure-compliance` | microsoft/azure-skills | 516,198 |
|
||||
| 49 | `azure-aigateway` | microsoft/azure-skills | 516,058 |
|
||||
| 50 | `azure-kusto` | microsoft/azure-skills | 515,980 |
|
||||
|
||||
## Notable Categories
|
||||
|
||||
The top 50 breaks down into these groups:
|
||||
|
||||
* Development workflow: find-skills, grill-me, tdd, handoff, triage, prototype.
|
||||
* Design and frontend: frontend-design, vercel-react-best-practices, web-design-guidelines.
|
||||
* Lark office suite: 22 skills from open.feishu.cn, roughly ranks 12-35.
|
||||
* Azure infrastructure: 13 skills from microsoft/azure-skills, ranks 38-50.
|
||||
* Agent orchestration: agent-browser, setup-matt-pocock-skills.
|
||||
|
||||
`find-skills` leads by a wide margin with 2.9 million installs. The Lark suite and Azure suite dominate the middle of the list.
|
||||
|
||||
## SKILL.md Format
|
||||
|
||||
A skill is a directory that contains a `SKILL.md` file:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
description: What this skill does
|
||||
---
|
||||
```
|
||||
|
||||
The `name` field is required and lowercase. The `description` field is required. Skills load progressively: discovery loads only the metadata, activation loads the full file on match.
|
||||
|
||||
## 2025/2026 Trends
|
||||
|
||||
* The Agent Skills spec is the common standard across 20+ agents.
|
||||
* Skills are write once, use everywhere.
|
||||
* Registries add security audits for skill content.
|
||||
* Specialized registries, such as QA, are emerging.
|
||||
|
||||
## Citations
|
||||
|
||||
* [skills.sh](https://skills.sh)
|
||||
* [skills.sh API `/api/skills/all-time/0`](https://skills.sh/api/skills/all-time/0)
|
||||
* [vercel-labs/skills](https://github.com/vercel-labs/skills)
|
||||
* [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)
|
||||
* [agentskills.io](https://agentskills.io)
|
||||
* [openai/skills](https://github.com/openai/skills)
|
||||
|
||||
## See Also
|
||||
|
||||
* [Agent Instruction Files](agents-files.md)
|
||||
* [Pi Plugins](plugins.md)
|
||||
* [Skills Documentation](../skills/index.md)
|
||||
+15
-3
@@ -23,7 +23,7 @@ Porkbun DNS-01, hot reload).
|
||||
|
||||
## [Gitea and tooling](tools/index.md)
|
||||
|
||||
Installed software: Gitea, llama.cpp/ornith, niri, ghostty, tmux, ComfyUI,
|
||||
Installed software: Gitea, llama.cpp, niri, ghostty, tmux, ComfyUI,
|
||||
CachyOS, skills tooling — each with its verified operational facts.
|
||||
|
||||
## [Pi-era agent setup](pi/index.md)
|
||||
@@ -31,9 +31,11 @@ CachyOS, skills tooling — each with its verified operational facts.
|
||||
The legacy pi agent configuration (~/.pi era): settings, models, packages,
|
||||
skills. Kept for reference; the live harness is OMP under `~/.omp`.
|
||||
|
||||
## [OMP packages and skills](packages/index.md), [skills index](skills/index.md)
|
||||
## [Skills tooling](skills/index.md)
|
||||
|
||||
Extensions and skills installed for the current OMP harness.
|
||||
The Agent Skills standard, the `skills` CLI, this fleet's store wiring, and
|
||||
the registries — for the live OMP harness. Pi-era packages are archived under
|
||||
[Pi-era agent setup](pi/index.md).
|
||||
|
||||
## [Core config](core/index.md)
|
||||
|
||||
@@ -48,7 +50,17 @@ Practice notes: SDLC, languages, infra tooling (Terraform, K8s, containers).
|
||||
Decision-support research: agentic web tooling, chezmoi evaluation,
|
||||
secrets-for-agents. Research docs inform decisions; they are not facts yet.
|
||||
|
||||
## [Agentic web research](agentic-web-research/index.md)
|
||||
|
||||
Self-hosted web-agent stack research: SearXNG tuning, VPN routing, agentic
|
||||
search practices, open models, MCP.
|
||||
|
||||
## [Inventory](inventory/index.md)
|
||||
|
||||
Pre-pruning census of every userspace config on this box — the input for the
|
||||
pruning session.
|
||||
|
||||
## [Change history](log.md)
|
||||
|
||||
Chronological update history of this bundle — incident lessons land here first,
|
||||
then settle into concept pages.
|
||||
|
||||
+186
-308
@@ -6,401 +6,279 @@ tags:
|
||||
- okf
|
||||
- maintenance
|
||||
- changelog
|
||||
timestamp: 2026-08-28
|
||||
timestamp: 2026-10-19
|
||||
---
|
||||
|
||||
# Bundle Change Log
|
||||
|
||||
Entry law (since 2026-10-19): one dated entry = what changed + the durable
|
||||
lesson, a few lines. Full incident narratives are recoverable from git
|
||||
(`git log --follow omp-docs/log.md`); knowledge that outlives an entry lives
|
||||
on its concept page, linked here. Never re-expand an entry in place.
|
||||
|
||||
## 2026-10-19 — dankvoice: humanized narration and thinking aloud (Refs #27)
|
||||
|
||||
dankvoice answered in verbatim markdown-cleaned text while the built-in
|
||||
vocalizer speaks humanized prose — the bundle's `Qyr` enhancer (`speech.enhanced`,
|
||||
system prompt `T6o`) now lives in the extension: every spoken unit is rewritten
|
||||
by the @tiny role (resolved from `modelRoles.tiny` in config.yml + the provider
|
||||
baseUrl in models.yml → frank-zealot :7771) under the same budgets (1536 tokens,
|
||||
6 s, 4000-char window), with mechanical cleanup as the fallback and an empty
|
||||
rewrite skipping the unit. Auto-speak also narrates the last assistant message's
|
||||
thinking blocks before the answer (`narration: true` blocks count as answer
|
||||
text); both are menu-toggleable and persisted (`thinking` in the settings file),
|
||||
env levers `DANKVOICE_REWRITE_URL/MODEL/REWRITE=0/THINKING/OMPCONFIG`. The
|
||||
fixture grows a chat route with echo/prose modes; 7 new scenarios, 22 green.
|
||||
Live smoke: a markdown answer became 3 sequential prose segments through real
|
||||
zealot + frank-tts, thinking played before its answer.
|
||||
Spoken units are rewritten by the `@tiny` role (frank-zealot) under the
|
||||
bundle's speech budgets before synthesis, with mechanical cleanup as fallback;
|
||||
auto-speak narrates the last message's thinking blocks first; all toggles
|
||||
persist. 7 new scenarios, 22 green; live smoke through real zealot + frank-tts.
|
||||
|
||||
## 2026-10-19 — dankvoice: segmented sequential speech, copied from the bundle's vocalizer
|
||||
## 2026-10-19 — dankvoice: segmented sequential speech
|
||||
|
||||
Silent-answer incident follow-up: `agent_end` awaiting one whole-answer
|
||||
synthesis hit the harness's 30 s extension-handler timeout
|
||||
(`handler timed out after 30000ms`) on long answers, and the single frank-tts
|
||||
request for the entire answer was the stall. Instead of inventing a heuristic,
|
||||
ported the utterance-splitting state machine out of the built-in speak-aloud
|
||||
vocalizer (minified class `fHe` in `dist/cli.js`): strong boundaries are
|
||||
`[.!?…]+` runs followed by whitespace — `!!!!!`/`...` stay one cut — with
|
||||
abbreviation and inline-code guards; `3.5`/`1,5` survive because a boundary
|
||||
needs trailing whitespace; fenced code and tables swallow whole; headings and
|
||||
bullets vanish, ordered markers speak their number ("1, "); links collapse to
|
||||
labels, URLs to hosts, paths to basenames; run-ons break at commas or word
|
||||
wraps before 280 chars. `speak()` now synthesizes segment N+1 only after
|
||||
segment N's player exited — strictly sequential, audio never stacks — and
|
||||
`agent_end`/`/say <text>` fire-and-forget a chain retired through a run token
|
||||
by `/say stop`, disarming, or a newer utterance. `DANKVOICE_MAX` became a
|
||||
per-answer budget of whole leading segments; the hand-rolled `stripForSpeech`
|
||||
truncator is gone. No LLM "humanization" rewrite happens (the bundle's
|
||||
`speech.enhanced` rewrites with the tiny/smol model; dankvoice speaks
|
||||
mechanically cleaned text through the cloned voices). Tests: two new driver
|
||||
scenarios plus two rewrites, 17/17 in `tests/dankvoice.bats`.
|
||||
`agent_end` awaiting one whole-answer synthesis hit the harness's 30 s
|
||||
extension-handler timeout — lesson: extensions must never await work that can
|
||||
exceed 30 s. Ported the built-in vocalizer's utterance-splitting state machine
|
||||
(boundary = `[.!?…]+` + whitespace, abbreviation/code guards, per-answer
|
||||
segment budget); segments synthesize strictly sequentially. `DANKVOICE_MAX` is
|
||||
now a segment budget. 17/17 in `tests/dankvoice.bats`.
|
||||
|
||||
## 2026-10-18 — dankvoice: `/say` options menu with output-device routing (Refs #23)
|
||||
|
||||
Added `/say menu` (bare `/say` now opens it; `help` keeps the text listing), the
|
||||
pi-peon-style settings surface: auto-speak toggle, voice picked from the frank-tts
|
||||
roster, **output device** (PipeWire sinks via `wpctl` → `pw-play --target` /
|
||||
`paplay --device=`), player binary, spoken-char cap, and a "speak a test phrase"
|
||||
utterance that proves the audio path audibly. Choices persist to
|
||||
`~/.omp/cache/dankvoice.json` (`DANKVOICE_CONFIG`); env now wins over that file,
|
||||
which wins over defaults — answering the silent-session incident where
|
||||
PipeWire's remembered Bluetooth route played synthesized answers into nowhere.
|
||||
`detectPlayer` becomes `availablePlayers` + `playerFor`. Tests gain a fixture
|
||||
`wpctl`, a scripted `select` in the driver, and three menu scenarios: 15 green
|
||||
in `tests/dankvoice.bats`, 51 green suite-wide.
|
||||
`/say menu` (pi-peon-style): auto-speak, voice, PipeWire output device
|
||||
(`wpctl` → `pw-play --target`), player, char cap, test phrase. Precedence
|
||||
env > `~/.omp/cache/dankvoice.json` > defaults — born from the incident where
|
||||
PipeWire's remembered Bluetooth route played answers into nowhere.
|
||||
|
||||
## 2026-10-18 — dankvoice: the cloned voices finally speak in the TUI (Refs #21)
|
||||
|
||||
Nothing in the harness could pronounce them: the TUI vocalizer and `omp say` gate `--voice` against the bundled Kokoro enum (`omp say --voice narrator1 "test"` → `error: Expected --voice to be one of: af_heart, …`), so frank-tts was reachable only as a file. Added `agent/extensions/dankvoice.ts` — `/say <text>`, `/say on|off` (narrate the final answer at `agent_end`), `/say voice|voices|stop|status` — synthesizing over the OpenAI speech route and playing through `pw-play`/`paplay`/`ffplay`, with the endpoint read from the `api: openai-speech` row of `agent/models.yml` (no host, no secret in the file). Verified live in a real TUI session on the workstation: roster `GET /v1/audio/voices` → `narrator1, narrator2, narrator3`; `/say` produced 99,884 B / 2.08 s and 69,164 B / 1.44 s WAVs handed to the player, temp dirs cleaned afterwards; `/say on` armed the footer (`🔊 narrator1`) and each following finished turn spoke its answer (1.20 s WAV), an unknown voice name answered with the roster instead of speaking, and an `agent_end` carrying `willContinue` (the harness scheduled an auto-retry) is deliberately never narrated. Extension discovery itself proved with a probe file in `~/.omp/agent/extensions/` loaded by a fresh `omp -p` run. Reference page [dankvoice](core/dankvoice.md), registered in the core index; black-box seam `tests/dankvoice.bats` (12 tests).
|
||||
The harness gates `--voice` against the bundled Kokoro enum, so frank-tts's
|
||||
cloned voices were unreachable in-TUI. Added `agent/extensions/dankvoice.ts`
|
||||
(`/say …`) synthesizing over the OpenAI speech route, endpoint read from the
|
||||
`api: openai-speech` row of `agent/models.yml` (no host or secret in code).
|
||||
|
||||
## 2026-10-18 — Noctalia bar layout clobbered by trunk-sync stash, recovered from dangling objects
|
||||
## 2026-10-18 — Noctalia bar layout clobbered by trunk-sync stash, recovered
|
||||
|
||||
Frank's months of GUI-built bar customizations (cat/clock/clock-utc/weather start, taskbar center, capsule groups g1–g4, control-cheat-sheet, thickness/font-scale/opacity styling) vanished from the live bar at 16:46. Root cause: the layout existed **only in the working tree** — the repo copy of `settings.toml` carried a stale plain layout because GUI edits hadn't been committed inside the hourly heartbeat window — and a trunk-sync session clearing the dirty tree for `origin/main` stashed it; the stash entry was subsequently destroyed (three `WIP on main` stashes within 60 s, all later dropped). Recovery: `git fsck --lost-found` surfaced the destroyed stash as dangling commit `7fe3ed8` (16:46:09); candidate validated in a sandboxed `XDG_*_HOME` before restore, clobbered file preserved to `.AGENTTRASH/`, layout restored through the symlink target and proven by screenshot, committed as `c87b378` — the durable copy the layout never had. Lessons codified into managed skills: trunk-sync must preservation-**commit** every dirty deployment path (never stash, never `stash clear`), and GUI layout edits get committed the same session they're made.
|
||||
GUI-built bar customizations existed only in the working tree; a trunk-sync
|
||||
stash-then-drop destroyed them. Recovery: `git fsck --lost-found` surfaced the
|
||||
dropped stash as a dangling commit; validated in a sandboxed `XDG_*_HOME`
|
||||
before restore. Lesson: GUI-written config is only durable once committed —
|
||||
the motivation for the live-sync heartbeat below.
|
||||
|
||||
## 2026-10-18 — Fleet law: issue/PR attribution footers
|
||||
|
||||
Every agent-opened issue and PR body now ends with a `cwd:` + `session:` footer (session id from `/status`), in AGENTS.md of both `dank/command-center` and `dank/serverAppConfigs` (mirrored PRs). Born from the live-sync review: once the machine starts filing and committing on its own, its artifacts must trace back to the box and session that produced them.
|
||||
Every agent-opened issue/PR body ends with `cwd:` + `session:` footer, in both
|
||||
`dank/command-center` and `dank/serverAppConfigs` AGENTS.md: machine-made
|
||||
artifacts must trace to the box and session that produced them.
|
||||
|
||||
## 2026-10-18 — live-sync heartbeat for machine-written paths (Refs #11)
|
||||
|
||||
Root-caused the month of silent divergence in the live checkout (~61 auto-learned skills on one disk only, a stranded `unexpectedStopDetection` fix, merge-refusals from dirty trees): the checkout IS the deployment, symlinks make machine writes dirty tracked files by design, and no commit law covered that churn. Added `scripts/live-sync.sh` + systemd user timer — allowlist tiers (memories, managed-skills, live config, dotfiles) auto-commit with hooks armed, merge `origin/main`, push, and reap stale `wt/*` worktrees; everything outside the allowlist is never staged, conflicts abort-and-alert. Black-box suite `tests/live-sync.bats` (9 tests). Tier law in AGENTS.md § Live-sync tiers; reference page `tools/live-sync.md` registered in the tools index.
|
||||
A month of silent divergence in the live checkout proved the checkout-is-
|
||||
deployment model needs a committer: `scripts/live-sync.sh` + systemd user
|
||||
timer auto-commits allowlisted tiers (memories, managed-skills, live config,
|
||||
dotfiles) with hooks armed, merges `origin/main`, pushes, reaps stale `wt/*`.
|
||||
Non-allowlist dirt never staged; conflicts abort-and-alert. See
|
||||
[tools/live-sync.md](tools/live-sync.md); tier law in AGENTS.md.
|
||||
|
||||
## 2026-10-18 — Fleet law: filed PRs open in Frank's browser immediately
|
||||
|
||||
Both repos' git rules now require it: the moment a PR is opened, `xdg-open <PR-URL>` drops a Firefox tab on the workstation (AGENTS.md § Trunk-based SDLC here; § Git Workflow step 6 in `dank/serverAppConfigs`, riding their PR #6 branch).
|
||||
`xdg-open <PR-URL>` the moment a PR opens — codified in both repos' git rules.
|
||||
|
||||
## 2026-10-18 — Trunk law: extension route closed unmerged; direct repo alignment instead
|
||||
## 2026-10-18 — Trunk law: extension route closed unmerged; direct repo alignment
|
||||
|
||||
Built and live-verified a cwd-scoped `before_agent_start` extension (quote probes: fires under `~/Projects`, silent elsewhere; kept as `.AGENTTRASH/trunk-law.js`). **Operator closed PR #9 unmerged** in favor of editing each repo's own AGENTS.md. Durable finding from the exploration: every context-file provider (AGENTS.md walk-up, `.omp/` dirs, CLAUDE.md) resolves at or below the repo root — a `~/Projects/AGENTS.md` for ancestor scope can never load; user-level `APPEND_SYSTEM.md` broadcasts to *all* sessions. Second finding: **serverAppConfigs never had git-flow** — its AGENTS.md mandated no branch regime at all (direct commit+push); a trunk + PR law is being added there by PR in that repo, not corrected.
|
||||
Operator closed PR #9 (cwd-scoped `before_agent_start` extension) in favor of
|
||||
editing each repo's AGENTS.md. Durable findings: every context-file provider
|
||||
(AGENTS.md walk-up, `.omp/` dirs, CLAUDE.md) resolves at or below the repo
|
||||
root — ancestor-scope files can never load; user-level `APPEND_SYSTEM.md`
|
||||
broadcasts to all sessions; serverAppConfigs never had git-flow.
|
||||
|
||||
## 2026-10-18 — SDLC switched to trunk-based development
|
||||
|
||||
`develop` retired by operator decision (single-dev repo; the branch bought nothing and cost a back-merge every release). New law in AGENTS.md § *Trunk-based SDLC*: branch off the freshest `origin/main` before every work item, PRs target `main` directly, `--no-ff` merges, tags `vX.Y.Z` straight on main. No back-merges, no release branches. The last back-merge (`527596a`) lands with this switch; the managed skill `gitflow-back-merge-plumbing` is now historical.
|
||||
`develop` retired (single-dev repo). Law in AGENTS.md § Trunk-based SDLC:
|
||||
branch off freshest `origin/main`, PRs target `main`, `--no-ff` merges, tags
|
||||
`vX.Y.Z` on main. Managed skill `gitflow-back-merge-plumbing` is historical.
|
||||
|
||||
## 2026-10-18 — Sibling-vault overlap census; system docs realigned to live ground truth
|
||||
|
||||
Census of `omp-docs/` against `~/Projects/serverAppConfig/serverAppConfigs-docs/` (subagent + live-ssh verification) found four contradicting pairs; all OURS-side stale pages corrected, THEIRS side flagged only (their repo, their PR flow). Ground truth from read-only probes on both boxes 2026-10-18.
|
||||
Census of `omp-docs/` vs `serverAppConfigs-docs` (subagents + live-ssh probes)
|
||||
found four contradicting pairs; ours fixed, theirs flagged for their PR flow.
|
||||
Recorded then: RTX 3090 moved Dankserver→Dankclaw 2026-09; dankserver = 2×
|
||||
Radeon AI PRO R9700 (the "board swap" story was false); served models per
|
||||
live units. Current state always: [/system/index.md](/system/index.md)
|
||||
(27B-era zealot figures here are historical; live census 2026-10-19 below).
|
||||
|
||||
* **Hardware drift corrected** (`system/dankserver.md`, `system/dankclaw.md` rewritten, `AGENTS.md` machine table): RTX 3090 moved Dankserver→Dankclaw 2026-09; dankserver now 2× Radeon AI PRO R9700 (7700X stays — the "board swap" story is false), 246 GiB RAM, no swap; dankclaw 121 GiB RAM + 64 GiB swap. Served models per live units: frank-archon (:7770 dankserver, radiance TP=2 iq4r), frank-dragoon (:7770 dankclaw, halogen NATIVE v2, iGPU), frank-zealot (:7771 dankclaw, llama.cpp PrismML, Ternary-Bonsai-2-27B PQ2_0, 3090). Both kernels 7.0.0-38-generic; dankclaw :7770 needs no auth.
|
||||
* **Gitea pages corrected** (`tools/gitea/` index + 3 subpages): `gitea-caddy` quadlet retired — fleet Caddy fronts the domain; data tree is `/home/dank/Containers/gitea/{data,postgres,env}` (2026-09-01 standard), `/opt/gitea/` is a do-not-use leftover; LAN IP, live domain, no WAN address.
|
||||
* **Pi-era pages demarcated as archive** (`pi/index.md`, `core/index.md` banners; `core/index.md` said settings.md was "Current"): `frank-default-small/large` endpoints, role tables, and 3090/4070 hardware rows now read as pi-era records. `tools/llama-cpp/index.md` fleet note modernized to the one remaining llama.cpp endpoint (zealot :7771).
|
||||
* **Their-side staleness flagged, NOT edited** (for operator clarification): `Agent/OMP Harness.md` still says thresholdPercent 70 — live config is **95** (`agent/config.yml:84`); `index.md:18` says Dankserver Ubuntu 24.04 vs their own specs page 26.04; `Dankclaw/Stack.md` "current mapping (2026-09-03)" predates the ACTIVE dragoon/zealot runbooks it links beside; `index.md:548` links the superseded pi-era KB at `~/.pi/agent/docs/`.
|
||||
* Consistent duplicates (no action): niri/noctalia desktop pages, Caddy reference. Divergence clarified: their "composer" = OpenWebUI chat box; ours = omp composer shape — unrelated subjects.
|
||||
## 2026-10-18 — Status line rebuilt on custom segments; full-source audit
|
||||
|
||||
## 2026-10-18 — Status line docs truth audit (full-source re-verification)
|
||||
New page [core/statusline.md](core/statusline.md) with an audit log — four
|
||||
first-pass claims were false and corrected against the minified bundle + a
|
||||
live screenshot matrix (context meter is `box`/`band` only; `composer.shape`
|
||||
routes segment arrays; `mode` states = Plan/Prewalk/Goal/Vibe/Loop). Bar
|
||||
rebuilt on `band` + custom segments; frank-archon display name slimmed in
|
||||
models.yml.
|
||||
|
||||
Exhaustive claim-by-claim re-audit of [OMP Status Line Customization](/pi/statusline.md) against the minified `dist/cli.js` bundle plus a live screenshot matrix (band × {off, percentage, embedded}, claude × off). Page carries an **Audit log** section; four first-pass claims were false and are corrected (see there): claude's rule is *not* the context meter (meter is `box`/`band` only; the "red rule" was the session-accent filler), the "Tern-only" composer-bar claim was bogus (the readout is `composer.tokenRate`, default off), `segmentOptions` are **not** gated to `preset: custom` (only the segment arrays are), and the `mode` segment's states are Plan/Prewalk/Goal/Vibe/Loop (no yolo). Page expanded with: the 7-preset defaults table, per-shape `statusAttachment`/`bottomBar` model (8 built-ins + plugin shape registry), `contextLine` per-value behavior, the 27-segment catalog with triggers/options, `segmentOptions` schema, and the full `statusLine.*`/`composer.*` knob registry. The bundle's own "(box composer only)" knob description for `contextLine` is upstream-wrong — band honors it.
|
||||
## 2026-10-09 — Blankpad DE redesign: desk profiles, keybinds, Handy wiring
|
||||
|
||||
ServerAppConfigs-docs overlap census: flagged separately for the operator (morning report); no doc merged/changed on either side.
|
||||
Per-desk niri profiles keyed by EDID long name (connector names reshuffle
|
||||
between docks; identity travels) + `scripts/desk.sh`; niri 26.04 has **no
|
||||
hotplug event** (`OutputConfigChanged` is only an ACK per niri-ipc) — the
|
||||
autoswitch daemon diffs output sets on `WorkspacesChanged`. Keybind cheat
|
||||
sheet now generated (`scripts/gen-keybinds.sh`); noctalia docs corrected to
|
||||
the v5 `noctalia msg` API. Handy: niri owns autostart; open breaker —
|
||||
frank-secondary answers in `reasoning_content` with empty `content`, and
|
||||
Handy cannot send `chat_template_kwargs.enable_thinking=false`. 27/27 green.
|
||||
|
||||
## 2026-10-18 — Status line rebuilt on custom segments; frank-archon display name slimmed
|
||||
|
||||
Interactive tune-up of the omp status bar (grilling session, live loop: config edit → watcher repaint → niri screenshot verify). New knowledge page: [OMP Status Line Customization](/pi/statusline.md).
|
||||
|
||||
* **Mechanics discovered:** `leftSegments`/`rightSegments` are inert unless `preset: custom` (fleet was on `nerd` with dead arrays; `segmentOptions` *do* merge under named presets); `composer.shape` routes them — `band` merges both arrays into one row above the editor (title rides the working row), `claude` splits them into top chip + bottom strip. The context meter exists **only in `box`/`band`** — `contextLine`: `off` plain rule, `embedded` hoists the context segment into the labeled inline meter (`60% ——— × 200K`), `percentage`/`annotated` paint an unlabeled proportional rule meter (all four live-verified); every other shape's rule is a constant session-accent filler. Working row (session title + tok/s readout gated by `composer.tokenRate`, default off) is composer chrome — model/thinking can never join it. Eight composer shapes ship in the bundle; plugins can register more.
|
||||
* **Final bar (`band`, after a `claude` sojourn):** left = `session_name · vim · mode · hostname · path · git(no branch text) · pr`; right cluster in array order = `model · cost · time_spent` (`context_pct` hoists out of the run to paint the labeled inline meter `60% ——— × 200K` as a flexible spacer between the groups). Cut: tok/s duplicate, clock, cache trio, `context_total`, `subagents`, `session` hash, and `token_in`/`token_out` (cumulative totals live in `/session`). `path`: logical `project/worktree` label (`stripWorkPrefix: true`, kept after a live `false` trial of the full cwd); branch text dropped (worktree branches are autogenerated), dirty badges kept.
|
||||
* **models.yml:** frank-archon display `name` slimmed to `"frank-archon"` (endpoint suffix dropped; `id` untouched).
|
||||
* **Out of scope noted:** worktree name generation (`wt-<date>-<hash>`) is omp-internal; possible upstream feature request.
|
||||
|
||||
## 2026-10-09 — Blankpad DE redesign: desk profiles, keybind rework, Handy fleet wiring
|
||||
|
||||
Branch `blankpad-de-redesign` (worktree `wt/de-redesign-20261009`). Full sweep + redesign of the niri/noctalia/Handy stack on blankpad.
|
||||
|
||||
* **Desk profiles.** `cfg/display.kdl` retired to a symlink; per-desk profiles `desk-1-home.kdl` / `desk-2-portable.kdl` declare monitors by **EDID long name** (`// requires:` lines) — connector names reshuffle between docks, identity travels. `scripts/desk.sh` = list/current/switch/cycle/match/capture; apply = relink → `niri validate` (rollback on failure) → `load-config-file` → noctalia notification. `scripts/desk-autoswitch.sh` + `blankpad-desk-autoswitch.service` watch `niri msg --json event-stream`: niri 26.04 has **no hotplug event** (`OutputConfigChanged` is only an ACK that an IPC/config output change was Applied, per niri-ipc); the daemon diffs the sorted output set carried by `WorkspacesChanged` and hot-applies the matching profile (debounced 1.5 s). Proven live with an eDP-1 off/on cycle: `[DP-2 eDP-1] → [DP-2] → [DP-2 eDP-1]`, apply + reload each time. PM1601 EDID still uncaptured (panel disconnected) — connector-keyed placeholder, `desk.sh capture` pending.
|
||||
* **Keybinds.** `swap-window-left/right` on Mod+CTRL+H/L; move-column demoted to Mod+CTRL+Alt+H/L; 7 column-width presets 12.5–87.5 %; Print trio (full / gui / screen) via noctalia screenshot IPC; launcher Mod+D; Alt+Tab → noctalia window-switcher; Mod+V → clipboard panel (id verified live); Mod+Shift+D → desk cycle; Mod+Shift+Space → `handy --toggle-post-process`; lid-close → `noctalia msg session lock-and-suspend` (pairs with logind `HandleLidSwitch=ignore`). Cheat sheet now GENERATED: `scripts/gen-keybinds.sh` → `omp-docs/tools/niri/keybindings.md` (119 bindings).
|
||||
* **Noctalia.** `config.toml` + `settings.toml` (lives in `~/.local/state/`, not `~/.config/`) tracked; `taskbar` widget added to bar center, applied live via `noctalia msg config-reload`. Docs corrected to the v5 `noctalia msg` API.
|
||||
* **Handy.** Self-autostart killed (`~/.config/autostart/Handy.desktop` → `.AGENTTRASH`; `autostart_enabled=false`); niri owns autostart (`spawn-at-startup "handy" "--start-hidden"`). Fleet post-processing wired into the live store: provider `custom` → `http://192.168.0.143:7771/v1`, model `frank-secondary`, prompt `default_improve_transcriptions`. **Open breaker:** frank-secondary answers in `reasoning_content` and leaves `content` empty; per-request cure `chat_template_kwargs.enable_thinking=false` verified, but Handy cannot send it and the server is shared with fleet compaction — dedicated no-think port proposed. 0.9.6→0.9.8 upgrade is operator-owned (`yay -Syu handy-bin`).
|
||||
* **Scripts + tests.** Two subagents died mid-run (one mid-test-write; one crashed **looping `sudo yay` without a TTY** — see next entry). Their scripts/tests were rebuilt from live-format ground truth: `tests/desk.bats` (16), `tests/gen-keybinds.bats` (6), `tests/niri-config.bats` (5, incl. real `niri validate` on the assembled base+zz tree with each desk profile active). Suite: 27/27 green.
|
||||
|
||||
## 2026-10-09 — Incident: agent sudo-loop tripped pam_faillock and locked out the operator's sudo
|
||||
|
||||
While attempting the Handy 0.9.8 install, a subagent ran `sudo yay -Syu handy-bin` in a retry loop for ~15 minutes. Harness sudo has no TTY, so every attempt logged 3 `pam_unix` auth failures; `pam_faillock` (deny=3) locked user `blank` out — the operator's own correct-password `sudo`/`pacman -Syu` began failing with "temporarily locked out", which looked exactly like a changed password.
|
||||
|
||||
* **No password change:** `/etc/shadow` mtime 2026-09-10 23:31, untouched; no `passwd`/`chpasswd`/`usermod` in the journal.
|
||||
* **Recovery:** loop process died with the agent; `faillock --user blank --reset` (unprivileged for own user, dir `/run/faillock/blank` is 0700) cleared the counter; verified empty.
|
||||
* **New law:** agents NEVER run `sudo`/`yay`/`pacman`/`pkexec` on Frank's workstations — root-requiring steps are handed to the operator as exact copy-paste commands. Codified as managed skill `faillock-sudo-lockout-recovery`.
|
||||
## 2026-10-09 — Incident: agent sudo-loop tripped pam_faillock, locked out the operator
|
||||
|
||||
A subagent retried `sudo yay` (no TTY) for ~15 min; `pam_faillock` deny=3
|
||||
locked user `blank` — correct-password sudo failed, mimicking a password
|
||||
change. Recovery: `faillock --user blank --reset`. Law: agents never run
|
||||
`sudo`/`yay`/`pacman`/`pkexec`; root steps go to the operator as exact
|
||||
commands. Skill `faillock-sudo-lockout-recovery`.
|
||||
|
||||
## 2026-10-09 — Full secret audit of the command-center repo: clean
|
||||
|
||||
Five-layer audit of `dank/command-center` at `79e780f`, driven by the four live values in `~/.config/secrets/` (gitea, hf_token, hf_token_write, kagi_api_key) plus 21 provider shapes (sk-, hf_, gh[pousr]_, glpat-, AKIA/ASIA, xox, npm_, pypi-, AIza, JWT, PEM/OpenSSH keys, `scheme://user:pass@host` basic-auth URLs, `password|secret|api_key = <literal>` assignments). Findings printed redacted (prefix + length + sha256 prefix).
|
||||
|
||||
* **Live-value scan — clean.** 77 revs (5 branches, 2 tags), 765 reachable blobs, 3.4 MiB of blob text: no known live value appears in any tracked blob at any ref.
|
||||
* **Whole object store, reachable *and* dangling — clean.** `git cat-file --batch-all-objects` finds 767 blobs; 2 are unreachable, never committed on any ref (`git log --all --find-object` empty). One is a 123 KB superseded memory page; the other is a 35-byte test fixture holding a synthetic `sk-` key whose body is the alphabet followed by `1234` — pattern-minted, not issued. No PEM key, no JWT, no basic-auth URL anywhere. (Quoting the literal here tripped the secret gate, which is the gate working as designed.)
|
||||
* **Shape hits, all triaged benign**: `api_key="sk-no-key-required"` (llama.cpp doc placeholder), `Set password:` / `authenticate(user, password)` prose in the Authentik memory skills, and a 40-hex string in the home-config census that is a git **packfile filename** (`pack-ff7cc541….pack`), not a token.
|
||||
* **Entropy layer — clean.** Zero tokens ≥ 32 chars with Shannon entropy ≥ 4.3 in HEAD blobs.
|
||||
* **Payloads, not just pointers**: all 23 git-lfs wallpaper objects (81 MiB) scanned as bytes — no secret shape in any payload.
|
||||
* **Quarantine list holds**: no tracked file matches `auth.json`/`trust.json`/`.env`/`*.pem`/`*.key`/`identity*`; the 42 ignored paths on disk carry no secret shape; no credential in any git config scope (local/global/system).
|
||||
* **Fixed on the spot**: `~/.config/secrets/hf_token_write` was mode 0644 (world-readable) → 0600. `~/.cache/huggingface/token` (the standard HF location, holds the same value) verified 0600.
|
||||
* **Known gap, not yet closed**: `.githooks/pre-commit` covers GitHub/GitLab/Slack/AWS/PEM/JWT/OpenAI-shaped `sk-`, but **not** `hf_…`, `npm_…`, `pypi-…`, `AIza…`, Stripe, Telegram, or a `scheme://user:token@host` basic-auth URL — which is exactly the shape that sat in `remote.origin.url` until today. Widening the gate is an open decision.
|
||||
Five layers (live-value scan across 77 revs/765 blobs, whole object store
|
||||
incl. dangling, shape triage, entropy ≥4.3, LFS payloads) — no secret in any
|
||||
reachable or dangling object; quarantine list holds. Fixed `hf_token_write`
|
||||
0644→0600. Open gap: the pre-commit gate lacks `hf_`/`npm_`/`pypi-`/`AIza`/
|
||||
Stripe/Telegram shapes and basic-auth URLs — widening it is an open decision.
|
||||
|
||||
## 2026-10-09 — Gitea token moved out of every remote URL
|
||||
|
||||
Both workstation clones (`~/.omp` → `dank/command-center`, `~/Projects/serverAppConfig` → `dank/serverAppConfigs`) carried the Gitea HTTP token inside `remote.origin.url`, so it sat in `.git/config`, was printed by `git remote -v`, and was echoed verbatim by the git-lfs lock warning on every push.
|
||||
Remotes bare; credential in `~/.config/secrets/gitea` (0600) behind a global
|
||||
`credential.helper store`. Trap (git 2.56.0, measured): `git
|
||||
credential-store` rejects the `protocol=`/`host=` block shape the man page
|
||||
shows — the store file must be one URL per line, port included. Verified with
|
||||
`GIT_TERMINAL_PROMPT=0`. Details: [tools/gitea/client-access.md](tools/gitea/client-access.md).
|
||||
|
||||
* **Cutover**: remotes are now bare (`http://192.168.0.143:3000/dank/<repo>.git`); the credential lives in `~/.config/secrets/gitea` (0600) behind a **global** helper — `git config --global credential.helper 'store --file ~/.config/secrets/gitea'` — so every repo on the host authenticates from one file. `lfs.…info/lfs.locksverify true` set on `~/.omp` to silence the warning that leaked the URL.
|
||||
* **The trap (git 2.56.0, measured)**: `git credential-store` will not parse the `protocol=`/`host=`/`password=` block shape that `git credential fill` accepts on stdin and that the man page shows for `~/.git-credentials`. It returns an empty `get`, and git falls through to askpass: `could not read Username for …`. The store file must be one URL per line, port included: `http://dank:<token>@192.168.0.143:3000`.
|
||||
* **Verified** with prompts disabled (`GIT_TERMINAL_PROMPT=0`): `git credential-store get` returns the credential, `ls-remote` reads, `push --dry-run` says `Everything up-to-date` on both repos, `git remote get-url origin` contains no `@`, and a grep for the token across `~/.gitconfig`, both `.git/config` files, and the shell rc files returns nothing.
|
||||
* **Doc**: new [[client-access|client-access]] (`tools/gitea/client-access.md`) — credential file layout, the store-format trap, the verification loop, LFS lock warning, rotation procedure. Cross-linked from the gitea index and management pages.
|
||||
## 2026-10-09 — Working tree reconciled: callsign renames, compaction move, gitignore quarantine
|
||||
|
||||
## 2026-10-09 — Working tree reconciled: callsign renames, Dankclaw compaction, gitignore quarantine
|
||||
|
||||
A 200-entry dirty tree (116 deleted, 73 untracked, 11 modified) sat uncommitted across several sessions. Committed as seven atomic units; nothing discarded.
|
||||
|
||||
* **Model ids renamed to the unit-name scheme** (`agent/models.yml`): `frank-medium → frank-archon` (dankserver :7770, 200,000 ctx / 16,384 max), `frank-large → frank-dragoon` (Dankclaw :7770, 217,088 / 45,056, `input: [text, image]`), `frank-small → frank-zealot` (Dankclaw-3090 :7771, 200,704 / 16,384). The **services keep the old names on the wire** — `/v1/models` still serves `frank-primary`, `frank-large`, `frank-secondary`; the engines accept an arbitrary request `model` id, so the rename is harness-side only. Probed live: all three chat completions return 200 with `reasoning_content`.
|
||||
* **Server-side compaction moved** off `192.168.0.235:7770` to `192.168.0.143:7771` (frank-zealot's 3090), threshold 70 % → 85 %, remote streaming v2 + async on; every model's `compactionModel` points at `frank-zealot` so the wire id stays valid at the compaction endpoint. Reference integrity checked programmatically: 22 model references across `modelRoles`, `task.agentModelOverrides`, `compactionModel` — zero unresolved.
|
||||
* **`.gitignore` quarantine** for runtime state that was tracked-adjacent noise: `autoresearch/`, `agent/predict/`, `local/`, `wt/`, and `agent/memories/--home-blank-.omp-wt-*` (a session inside a git worktree mints a memory bucket keyed on the ephemeral worktree path). All had zero tracked files, so the rules are purely additive — 73 untracked → 68, and the remaining 68 are real memory records that got committed.
|
||||
* **Skill libraries were renamed, not lost.** `agent/managed-skills` consolidated 94 → 25 (git renders directory renames as mass delete + mass add; pre-cutover content is intact at `12c5e88`). Workstation memory skills re-bucketed by topic: `dotfile-git-workflow` → `ghostty-text-aa` + `niri-display-rotation` + `noctalia-theme`, `handy-service-mgmt` → `handy-flm-inference`, `inference-runtime` → `llama-cpp-parallelism`.
|
||||
* **Display layout**: blankpad DP-2 back to landscape `3440x1440@239.999` (`transform "normal"`), HDMI-A-1 portrait bezel flipped `270 → 90`, eDP-1 re-pinned rightmost. Supersedes the 2026-09-15 portrait pin (`2baf0c0`).
|
||||
* **Secrets**: `.zshrc` now reads `KAGI_API_KEY` / `HF_TOKEN` from `~/.config/secrets/*` (600-perm files) instead of carrying literals into a repo published to Gitea. The pre-commit secret gate passed on all seven commits.
|
||||
200-entry dirty tree committed as seven atomic units. Harness model ids
|
||||
renamed `frank-{medium,large,small}` → `frank-{archon,dragoon,zealot}` —
|
||||
**services keep old names on the wire**; the engines accept any request model
|
||||
id, so renames are harness-side only. Server-side compaction moved to
|
||||
zealot's 3090 (threshold 70→85 %). `.gitignore` quarantine for worktree-keyed
|
||||
memory buckets and runtime dirs. Skill renames are not losses: git renders
|
||||
directory renames as mass delete+add; pre-cutover content intact at `12c5e88`.
|
||||
|
||||
## 2026-09-28 — Retired workstation purged from the knowledge base
|
||||
|
||||
Frank sold the client workstation. Every identifier for it is gone from this bundle: hostname, both of its LAN addresses, and its Wi-Fi SSID. The knowledge outlives the box; the machine does not.
|
||||
Sold box: hostname, both LAN addresses, Wi-Fi SSID gone bundle-wide; the
|
||||
knowledge distilled into [system/network.md](system/network.md) (multi-link
|
||||
resolver law: a static resolver must be pinned on each *connection*) and
|
||||
[tools/niri/displays.md](tools/niri/displays.md) (portrait transforms, the
|
||||
three ways a multi-monitor rig breaks). Hostname stays only where it is a
|
||||
lookup key (install.sh `--host`, `packages/<hostname>.pkgs`).
|
||||
|
||||
* **Distilled, not deleted.** The four per-host system pages carried two pieces of knowledge worth keeping and one that was not:
|
||||
* `/system/network.md` (new) — LAN topology, plus the multi-link resolver law: a client with two `+DefaultRoute` links flaps its DNS, and the fix is a static resolver pinned on each *connection* (a `resolved.conf` `DNS=` line is only a per-link fallback). Keeps the flush-caches verification loop, because one successful `dig` proves nothing on a flapping resolver.
|
||||
* `/tools/niri/displays.md` (new) — the multi-monitor rig: portrait transforms, absolute positions, the auto-placed third panel, the iGPU render-node pin, and the three ways it breaks (duplicate output blocks, positions that do not reflow, a mode the panel cannot drive).
|
||||
* Dropped: the machine's own spec sheet and quick-facts table. The OS and userspace facts they repeated already live in `tools/cachyos.md`.
|
||||
* **Mechanical scrub** across the rest of the bundle: indexes, tool and research pages, the inventory census, the changelog, one generated HTML report, and four managed skills. Facts kept, names dropped — `install.sh`'s `--host` case list and the `packages/<hostname>.pkgs` filename stay, because the hostname is the lookup key there.
|
||||
* `AGENTS.md` and `README.md` keep a nameless "workstation" row so the fleet tables still describe the class of box without advertising a machine that is no longer Frank's.
|
||||
* Out of scope by decision: `agent/memories/**` (past-session records the learn pipeline rewrites) and the retired pages' history — they are recoverable from `.AGENTTRASH/20260928-retired-workstation/` and from git.
|
||||
|
||||
## 2026-09-01 — Retry backoff and thinking default
|
||||
|
||||
* **Retry backoff**: configured Pi's automatic agent-level retries in `settings.json` with a 10-second base delay, producing 10s, 20s, and 40s delays across three retries.
|
||||
* **Thinking default**: set `settings.json` `defaultThinkingLevel` to `medium`. `models.json` has no supported per-model default-thinking field; Pi applies this global default to the configured models.
|
||||
## 2026-09-01 — Retry backoff and thinking default (pi era)
|
||||
|
||||
Pi `settings.json`: 10 s base retry backoff (10/20/40 s), `defaultThinkingLevel:
|
||||
medium` (no per-model thinking field exists in `models.json`).
|
||||
|
||||
## 2026-08-28 — KB rebuilt to OKF v0.1; live-verified fleet facts
|
||||
|
||||
* **Creation**: the whole `omp-docs/` bundle was copied from the legacy `~/.pi/agent/docs` tree and rebuilt as a git-tracked, OKF v0.1-conformant knowledge base inside the new `command-center` repo (repo root = live agent dir; the checkout *is* the deployment). Every checkable claim was re-verified against the live fleet (read-only probes); unverifiable claims are tagged `unverified` in frontmatter.
|
||||
* **Update — hardware facts corrected**: Dankserver is a **Ryzen 7 7700X + RTX 3090** (not Strix Halo); Strix Halo (gfx1151) is **Dankclaw**. RAM, storage, kernel, and network facts were probed live and corrected across `system/`.
|
||||
* **Update — conformance pass**: concept-in-disguise indexes promoted to `<dirname>.md` concept files (identity = path, per spec); index.md files stripped of frontmatter (indexes carry none); all wikilinks and relative links resolved or repointed; `scripts/kb-lint.sh` (OKF conformance + link-integrity linter) exits 0 on the bundle. Vendored `references/okf-spec.md` is exempt from link-lint — its example paths are illustrations, not links.
|
||||
* **Update — inventory**: home-config census (7 orphaned configs, 10 prune-candidates) recorded under `inventory/` for the pruning session; zero deletions performed. Legacy `~/.pi` tree left untouched and frozen.
|
||||
* **Deferred to operator** (decisions, not facts): chezmoi source layout (`research/chezmoi-evaluation.md` recommends a separate chezmoi repo) and the permanent secrets tool (`research/secrets-for-agents.md`; interim = pre-commit secret gate + quarantine list; top candidate sops+age). Gitea Projects unit is disabled instance-wide, so the kanban board is a one-time web-UI setup for the operator.
|
||||
`omp-docs/` copied from legacy `~/.pi/agent/docs`, rebuilt as git-tracked OKF
|
||||
v0.1 (checkout *is* the deployment); unverifiable claims tagged `unverified`.
|
||||
Conformance pass promoted concept-in-disguise indexes, stripped index
|
||||
frontmatter, resolved all links; `scripts/kb-lint.sh` exits 0. Hardware facts
|
||||
were corrected *then* (3090-on-dankserver since moved — see 2026-10-18).
|
||||
Inventory census recorded under `inventory/` for the pruning session.
|
||||
|
||||
## 2026-08-23 — Homepage deployed to production; Caddy KB doc
|
||||
|
||||
* **Homepage is live on Dankclaw.** `./scripts/deploy.sh dankclaw` deploys the static files to `/srv/homepage`, installs the status checker (systemd timer, every 3 min, writes `status.json`), writes `deployed.js` (the last master deployment datetime), renders the Caddyfile (both basicauth hashes from the host `.env`), reloads Caddy, and checks health. Verified end-to-end: `/admin/` (operator) + all shared files serve 200 under the operator credential; `/` and `/admin/` 401 without/wrong credentials; the LLM is healthy.
|
||||
* **Caddyfile auth design (the hard-won fix).** Caddy *sorts* top-level directives, so a `rewrite` runs before a `basicauth`; the rewrite changed `/admin/` to `/admin.html` and the path-based auth matchers then saw the rewritten path, applying the wrong (family) auth block — the operator password 401'd. Fix: serve each page from its own `handle` block (which preserves file order, so the auth is checked on the original path): `handle /admin*` (operator only), `handle @data` (shared data + assets, family OR operator, so the admin page's fetches reuse the operator credential), and a catch-all `handle` (family). Also: a `handle` inline matcher is a single token (multi-path needs a named matcher); a leading `@name <directive>` is parsed as a matcher *definition* (re-defines `@name`).
|
||||
* **Caddy mount fix.** The caddy container mounted the repo's `shared/homepage` (static source) to `/srv/homepage`; the generated files (`status.json`, `deployed.js`) are written to the host's `/srv/homepage`. Pointed the mount at the host's `/srv/homepage` so the generated files serve. A compose change needs a container *recreate* (not a reload) — `podman compose up -d caddy` (the deploy skips the compose restart, so this is manual).
|
||||
* **Caddy KB doc** (operator request: read the docs before guessing at syntax): new `caddy/` section in this bundle — [[caddyfile|caddyfile]] (`caddy/caddyfile.md`) + `caddy/index.md`, cross-linked from the root `index.md`. Grounded in caddyserver.com (fetched 2026-08-23) + a researcher subagent brief.
|
||||
* **Tests:** 116 green (was 112; +4 for the Caddyfile handle design + the `status.json` 0644 perms). The local `caddy validate` test is skipped (no local caddy binary); the rendered config is validated on the target via the porkbun image before each deploy.
|
||||
Homepage live on Dankclaw via `scripts/deploy.sh` (status checker timer,
|
||||
deployed.js, rendered basicauth hashes, health check). Hard-won Caddy lesson:
|
||||
top-level directives are *sorted*, so `rewrite` runs before `basicauth` and
|
||||
auth matchers saw rewritten paths — serve each page from its own `handle`
|
||||
block to preserve order; a `handle` inline matcher is a single token; a
|
||||
leading `@name <directive>` parses as a matcher definition. Now documented on
|
||||
[caddy/caddyfile.md](caddy/caddyfile.md). A compose mount change needs a
|
||||
container *recreate*, not a reload. 116 tests green.
|
||||
|
||||
## 2026-08-23 — Homepage design settled (grilling complete)
|
||||
|
||||
* **All 38 open questions (Q6–Q43) answered.** The homepage design is now fully settled. Full record: `serverAppConfigs/docs/Infrastructure/Homepage Design Grilling.md` (final decisions + the deltas) and `docs/Infrastructure/Homepage.md`.
|
||||
* **Key deltas from the initial recommendations:** the probe method is **per service** (`tcp` or `http`); the probe timeout is **5 s**; the layout is **TUI-style panels** (a grid), not a flat list; styling is **toggleable** (full theme default, a toggle to bare unstyled HTML); **do not alter the user's cursor**; **no client-side auto-refresh** (read `status.json` once on load); the footer shows the **last master deployment datetime** (not last-check); the deploy is **git-driven** (master = deployed state); the build is **full TDD**.
|
||||
* **Per-service docs workstream:** each service gets a `/docs/<svc>/` page (not `/usage/`), written as a **how-to for a regular user** (no maintenance details), password-protected by the same auth as its homepage section, built as each service goes active. The existing reference docs in `docs/` are NOT linked from the homepage (they may contain secrets).
|
||||
* **Build complete (all 6 slices, full TDD, 112 tests green):** 1 the checker core (tcp/wip/atomic write/generated_at), 2 the http probe, 3 the real `services.json` + schema, 4 the pages + theme + toggle, 5 the Caddyfile auth split (root vs `/admin/`), 6 the git-driven deploy. All committed + pushed. The render logic is verified with a Node DOM shim (9 user panels, correct summary, correct footer datetime).
|
||||
* **To go live:** the operator adds `CADDY_ADMIN_HASH` (the operator-only password, `caddy hash-password`) to the Dankclaw `.env`, then runs `./scripts/deploy.sh dankclaw`. Until then the admin hash stays a placeholder. The per-service `/docs/` pages, the *arr stack, and the optional `/how/` page remain separate threads.
|
||||
* **Correction (media stack):** the Dankserver media stack (RomM, Copyparty, Jellyfin, Plex, the *arr) is **UP** — it runs as **bare processes/services, not yet migrated to podman containers**. The 2026-08-22 "down / missing `.env`" finding was wrong: I was probing for the compose stack, which is not how it runs yet. Do not treat it as an outage and do not probe it as down. Its podman migration is a separate, future effort.
|
||||
All 38 open questions answered; full record lives in serverAppConfigs
|
||||
(`docs/Infrastructure/Homepage Design Grilling.md`). Key deltas: per-service
|
||||
tcp/http probes, 5 s timeout, TUI-style panel grid, no client auto-refresh,
|
||||
git-driven deploy, full TDD. Correction recorded: the Dankserver media stack
|
||||
runs as bare processes, not containers — never probe it as a compose stack.
|
||||
|
||||
## 2026-08-22 — vllmScripts merged into serverAppConfigs
|
||||
|
||||
* **Repo merge**: the `vllmScripts` repo (LLM inference fleet: serve scripts, systemd units, env tunables, deploy runbook, research docs) is merged into `serverAppConfigs` with its full git history (two-parent import commit, then reorganization: `docs/` → `docs/LLM/`, `scripts/` merged, `old/` for retired PP/NPU-era scripts). One repo, one checkout per host (`/home/dank/serverAppConfigs`), one `scripts/deploy.sh` covering both workloads per target (podman stack + LLM service relink/restart + both health checks).
|
||||
* **Units**: frank-default-{small,large,npu}.service now point at `/home/dank/serverAppConfigs/scripts/...`. The retired target checkouts (`/home/dank/vLLM` on Dankserver, `/home/dank/vllmScripts` on Dankclaw) are to be archived on the hosts during the production deploy.
|
||||
* **Secrets**: the live sudo password that the old vllmScripts AGENTS.md documented in plaintext is NOT carried into the merged repo (a bats leak-check guards it). It remains in the git history of both repos on the LAN Gitea — rotation recommended.
|
||||
* **KB links**: `system/index.md`, `system/dankserver.md`, `system/dankclaw.md`, and the root `index.md` updated — the "sibling knowledge bases" section is now a single sibling (serverAppConfigs, which contains the LLM fleet KB at `docs/LLM/index.md`).
|
||||
* **Port move**: `frank-default-large` (dankclaw) moved from `:52625` to `:7770` (operator request: the primary inference server sits on the standard llama.cpp port). Both LLM services now listen on `:7770`, distinguished by host. `models.json` (`llamacpp (dankclaw)`) and the OpenWebUI quadlet (`OPENAI_API_BASE_URL`) re-pointed to `:7770`. `pi/models.md` updated.
|
||||
* **Homepage design (grilling)**: the `serverAppConfigs` homepage (`docs/Infrastructure/Homepage.md`) is WIP — the Caddy site is live (basicauth 401, `:80` 302) but `/srv/homepage/` is not deployed. Settled design: a single site on Dankclaw (root = user services, `/admin/` = admin services behind a second operator-only password, optional `/how/` tourist page). Status is checked **server-side** — a systemd-timer checker (every 3 min) probes each backend `host:port` and writes a same-origin `status.json`; the page reads only that file (the client-side-ping design is blocked by cross-origin + mixed-content + auth). Full decision log + 38 open questions (Q6–Q43) in `docs/Infrastructure/Homepage Design Grilling.md`. A terminal-TUI-styled HTML progress report was generated for the operator to review and answer the open questions. Full-stack baseline verified: Dankclaw fully up; the Dankserver media stack is down (only Calibre-Web + the LLM are up; no `.env` on the target).
|
||||
Full-history two-parent import; one repo, one checkout per host, one
|
||||
`deploy.sh`. The plaintext sudo password from old docs was NOT carried over
|
||||
(a bats leak-check guards it); it remains in both repos' history on the LAN
|
||||
Gitea — rotation recommended.
|
||||
|
||||
## 2026-08-21 — Fleet ops: passwordless sudo, Hermes SSH keys, sibling KB links
|
||||
## 2026-08-21 — Fleet ops: passwordless sudo, Hermes SSH keys
|
||||
|
||||
* **Passwordless sudo**: added `/etc/sudoers.d/dank-nopasswd` (`dank ALL=(ALL) NOPASSWD: ALL`) on both Dankserver and Dankclaw. Verified `sudo -n true` on both. The pre-existing drop-ins (`frank-small` on Dankserver; `frank-large` + `frank-ling` on Dankclaw) grant per-command NOPASSWD for the frank restart scripts and remain in place.
|
||||
* **Hermes SSH keys**: the Hermes Agent (podman container `hermes`, project `dankclaw` in `serverAppConfigs`, gateway drops to container uid 10000 = host uid 109999, HOME `/opt/data` on a podman volume) now has a dedicated ed25519 key at `/opt/data/.ssh/id_ed25519` (`hermes-agent@dankclaw`) plus an SSH config for `dankclaw` (192.168.0.143), `dankserver` (192.168.0.235), and the workstation. The public key is in `dank`'s `authorized_keys` on all three machines. Verified from inside the container as the hermes user: all three `ssh <host> hostname` calls succeed.
|
||||
* **Sibling KB links**: `system/index.md`, `system/dankserver.md`, `system/dankclaw.md`, and the root `index.md` now link the two sibling knowledge bases on the workstation: `~/Projects/vllmScripts/` (inference fleet scripts + runbook, index `docs/index.md`) and `~/Projects/serverAppConfigs/` (Podman deploy configs for both servers, index `docs/index.md`).
|
||||
`/etc/sudoers.d/dank-nopasswd` on both servers (per-command drop-ins remain);
|
||||
dedicated ed25519 key for the Hermes container, verified into all three
|
||||
machines.
|
||||
|
||||
## 2026-08-19 — pi-web-access: SearXNG endpoint re-pointed to dankclaw
|
||||
## 2026-08-19 — pi-web-access: SearXNG endpoint re-pointed to dankclaw (pi era)
|
||||
|
||||
* **Config**: `~/.pi/web-search.json` — `searxngBaseUrl` moved from the dead `192.168.0.235:8081` (dankserver, connection refused) to `192.168.0.143:8081` (dankclaw; verified live: HTTP 200, 25 JSON results, 0.8 s). Deleted the redundant `provider: "all"` (the `searchProvider: "searxng"` pin already wins in v0.22). Added `maxInlineContentChars: 50000`. Kept `workflow: "none"` and `ssrf.allowRanges: ["192.168.0.0/24"]`.
|
||||
* **Docs**: `pi/packages/pi-web-access.md` bumped 0.14.0 → 0.22.0 (18-provider chain, config block, active-setup note, GitHub-clone section, yt-dlp present). `agentic-web-research/` SearXNG endpoint references repointed `.235` → `.143` (index, searxng-tuning, vpn-routing).
|
||||
* **Note**: pi-web-access caches `web-search.json` in memory per process — the new endpoint takes effect on the next Pi session, not the running one.
|
||||
* **Packages**: `yt-dlp` installed on the workstation (2026.07.04) — YouTube frame extraction now works; `ffmpeg` (n9.0.1) was already present.
|
||||
`searxngBaseUrl` moved off dead `.235:8081` to `.143:8081`; pi caches
|
||||
`web-search.json` per process — new endpoint needs a new session. `yt-dlp`
|
||||
installed (2026.07.04).
|
||||
|
||||
## 2026-08-19 — SearXNG + Gluetun bring-up on dankclaw
|
||||
|
||||
Field notes from standing up the search stack (gluetun + searxng + valkey) and confirming agentic JSON search. All four are operational; the SearXNG trio runs via podman-compose (not yet boot-persistent quadlet).
|
||||
Durable field notes (now on concept pages — see
|
||||
[agentic-web-research/vpn-routing.md](agentic-web-research/vpn-routing.md),
|
||||
[searxng-tuning.md](agentic-web-research/searxng-tuning.md),
|
||||
[engineering/infra/containers.md](engineering/infra/containers.md)):
|
||||
manual-WireGuard Proton needs `VPN_SERVICE_PROVIDER=custom` + the single-peer
|
||||
`WIREGUARD_*` env names (not `protonvpn`, not `WIREGUARD_PEERS_*`); gluetun
|
||||
ships no curl and `:8000` is the control server, not health; the limiter's
|
||||
JSON cap (`API_MAX=4`/hour) is hardcoded Python — `pass_ip` is the only
|
||||
bypass; rootless podman strips client IPs on published ports, so SearXNG must
|
||||
sit behind Caddy for XFF; quadlet generator rejects `CapAdd=`/`Device=` and
|
||||
generated units enable via `[Install] WantedBy=default.target`. ComfyUI on
|
||||
gfx1151: build on AMD's ROCm base and filter the torch family out of
|
||||
ComfyUI's requirements or you clobber the gfx1151 kernels.
|
||||
|
||||
* **Gluetun manual WireGuard**: a specific-server ProtonVPN config (private key + peer + endpoint) uses `VPN_SERVICE_PROVIDER=custom`, NOT `protonvpn`. The `protonvpn` provider is account/token-based and rejects a manually-set endpoint with `endpoint port is set`. Current Gluetun uses the single-peer model: `WIREGUARD_PUBLIC_KEY`, `WIREGUARD_ENDPOINT_IP`, `WIREGUARD_ENDPOINT_PORT`, `WIREGUARD_ADDRESSES` (not the old `WIREGUARD_PEERS_*` names). DNS is Gluetun's own `DNS_*` vars, not the WG `DNS` line.
|
||||
* **Gluetun healthcheck**: the image has no `curl`, and its `:8000` status server 404s on every path. Use `test: ["CMD","sh","-c","test -e /sys/class/net/tun0"]` — tun0 exists only while the tunnel is connected.
|
||||
* **SearXNG trusted group**: lives in `limiter.toml` (not `settings.yml`). A direct hit on the published port has no `X-Forwarded-For` header, so the bot-detection cannot resolve a client and returns 429 regardless of `pass_ip`. SearXNG must be reached through Caddy (which sets XFF); `trusted_proxies` then needs the podman bridge subnet (dynamic in rootless — pin the network CIDR) so Caddy's source is trusted for XFF extraction.
|
||||
* **Rootless podman gotchas**: short image names do not resolve (no unqualified-search registries) — qualify with `docker.io/`. Binding privileged ports (Caddy 80/443) needs the one-time sysctl `net.ipv4.ip_unprivileged_port_start=80`.
|
||||
* **Repo**: `serverAppConfigs` — added `shared/searxng/limiter.toml` + test seam, wired it into `deploy.sh`, fixed the Gluetun compose (peer env vars, qualified images, tun0 healthcheck), documented the rootless-port + Caddy/XFF gotchas, and skipped the ComfyUI GPU tests (migration pending).
|
||||
* **Boot-persistence (quadlet)**: converted the trio from podman-compose to quadlet so it survives reboot. searxng sets `Network=gluetun.container` (reuses gluetun's netns → exits the tunnel); gluetun + valkey join a pinned `searxng.network` (10.89.2.0/24). Deployed via `scripts/deploy-searxng-quadlet.sh`. Field gotchas (also in `engineering/infra/containers.md`): the generator rejects `CapAdd=`/`Device=` (use `AddCapability=`/`AddDevice=`) and silently skips the unit; generated units cannot be `systemctl enable`d — `[Install] WantedBy=default.target` is the enablement (`is-enabled` = "generated"), and linger makes them boot-start. Verified: all three `is-enabled` = generated, tunnel up (US-WA), agentic JSON search returns 27 on-topic results.
|
||||
* **open-webui moved to dankclaw (quadlet)**: the old open-webui was a bare container on Dankserver (:3000) pointing at a dead `:9090` backend. It now runs on Dankclaw as a boot-persistent quadlet (`scripts/deploy-open-webui-quadlet.sh`): CPU image `:main` (Dankclaw is CPU-only), isolated on `Network=slirp4netns`, published `:3005` (:3000 is Gitea's HTTP port), data at `/home/dank/Containers/open-webui/data`. Default LLM backend is the local vLLM (`host.containers.internal:52625`). The Dankserver `searxng` + `open-webui` bare containers were retired (data dirs preserved). `podman inspect <name>` can match an IMAGE, not just a container — a removed container still "exists" to inspect if its image remains; use `podman ps -a --filter name=` to check containers.
|
||||
* **Model/port mapping corrected (live, 2026-08-19)**: the fleet endpoints are the REVERSE of the 2026-08-17 note. Live truth (probed `/v1/models`): `frank-default-large` is on **Dankclaw :52625** (vLLM, completion) and `frank-default-small` is on **Dankserver :7770** (llama.cpp FastMTP, completion+multimodal). The `serverAppConfigs` docs (Stack, OpenWebUI) were corrected; the sibling `vllmScripts` KB still carries the old mapping and should be updated there.
|
||||
* **SearXNG 429 root cause (the "diva")**: the limiter's JSON cap is `API_MAX = 4` requests/IP/hour and that constant is **hardcoded in Python** (`searx/botdetection/ip_limit.py`), NOT settable in `limiter.toml`. The only bypass is `pass_ip` (SearXNG's `filter_request` returns before `ip_limit` runs when the IP is in `pass_ip`). Second gotcha: **rootless podman strips the client IP on published-port hits** — a request to the published port reaches the container with a slirp/bridge source (`10.88.x`/`10.89.x`), never the real client; only Caddy's `X-Forwarded-For` restores it. So even a LAN-IP curl 429'd. Fix: expand `pass_ip` to loopback (`127.0.0.1/32`, `::1`) + the host's private podman/slirp ranges (`10.88.0.0/16`, `10.89.0.0/16`) + the LAN. Verified: 20 concurrent JSON searches → all 200 (real results), while a spoofed public IP (8.8.8.8) still 429s (limiter still armed). The config file is root-owned (uid of the rootless podman namespace) — update with a one-off `sudo cp` + `systemctl --user restart searxng.service`.
|
||||
* **ComfyUI GPU (gfx1151) — DONE (Option 1/B)**: the deferred GPU ComfyUI is now built and running. It was previously a bare CPU venv (`/home/dank/ComfyUI`, py3.14, `torch 2.13.0+cu130` with no NVIDIA → CPU fallback). Now it's a **container** `comfyui-rocm:gfx1151` built from `dankclaw/Containerfile.comfyui` on AMD's `rocm/vllm:rocm7.12.0_gfx1151_..._py3.12_pytorch_2.9.1` base (the only torch build where `torch.cuda.is_available()=True` on the Strix Halo APU). Key gotchas: (1) the base image already ships the ROCm torch/torchvision/torchaudio, so the Containerfile must **skip the torch family** from ComfyUI's `requirements.txt` (an unpinned `torch` would clobber the gfx1151 kernels) — filter with `grep -viE '^(torch|torchvision|torchaudio)([^a-z]|$)'`. (2) **rootless podman cannot `--group-add render`** (gid 990 is outside the subgid range 100000+); GPU access comes from the `/dev/kfd`+`/dev/dri` passthrough checked host-side (the run user is already in `render`), so add only the `video` group. Verified: `/system_stats` → `cuda:0 Radeon 8060S`, logs show `AMD arch: gfx1151` + active HIP backend. Boot-persistent via a user systemd unit running `podman compose up -d comfyui` (old venv unit saved as `comfyui.service.venv.bak`). The 4 `comfyui_rocm.bats` tests are un-skipped (the group test now asserts video present + render ABSENT).
|
||||
## 2026-08-17 — Fleet redo + vLLM tool calling (pi era)
|
||||
|
||||
## 2026-08-17 — Fleet redo + vLLM tool calling
|
||||
Fleet moved off the pipeline-parallel + NPU topology; Quark W8A8 quant chosen
|
||||
over the Avesed INT8 for clean Qwen3 XML tool calls.
|
||||
|
||||
* **Update**: `pi/models.md` — providers rewritten for the fleet redo: `llamacpp (dankserver)` at :7770 and `vllm (dankclaw)` at :52625; model selection strategy and live defaults brought in line with the new topology and the Quark W8A8 model.
|
||||
* **Context**: the Frank fleet moved off the pipeline-parallel + NPU topology. `frank-default-large` (llama.cpp FastMTP, IQ4_XS) is on Dankserver; `frank-default-small` (vLLM ROCm, nameistoken Qwen3.6-35B-A3B Quark W8A8 INT8) is on Dankclaw with ngram spec and tool calling. The Avesed INT8 quant's tool-call XML fidelity was poor; the Quark quant follows the Qwen3 XML format cleanly.
|
||||
## 2026-08-16 — Gitea boot-persistence fix (dankclaw)
|
||||
|
||||
`unattended-upgrades` reboot exposed that the compose-era Gitea had no
|
||||
systemd units (~1 h down). Stack rewritten as quadlet (names, `systemd-gitea`
|
||||
network, linger + `WantedBy=default.target`, app.ini env-override gotcha, UID
|
||||
100999 ownership) across `tools/gitea/*`; `podman generate systemd` marked
|
||||
deprecated in [engineering/infra/containers.md](engineering/infra/containers.md).
|
||||
|
||||
## 2026-08-16
|
||||
## 2026-08-13 — Pi subagent limits recorded (pi era)
|
||||
|
||||
### Gitea Boot-Persistence Fix (dankclaw)
|
||||
Effective caps: globalConcurrencyLimit 2, parallel.maxTasks 8 / concurrency 4,
|
||||
maxSubagentDepth 2, turnBudget 30; no per-model limit. See
|
||||
[pi/packages/pi-subagents.md](pi/packages/pi-subagents.md).
|
||||
|
||||
* **Incident**: `unattended-upgrades` rebooted dankclaw at 15:01. The legacy podman-compose Gitea stack had no systemd units, so rootless podman did not auto-start the containers. Gitea was down ~1 hour.
|
||||
* **Update**: `tools/gitea/index.md`, `architecture.md`, `management.md`, `data-persistence.md` — rewritten for the quadlet-managed stack: container/unit names, the `systemd-gitea` network (DNS-enabled), boot persistence (linger + `WantedBy=default.target`), the app.ini env-override gotcha, UID 100999 ownership, incident log.
|
||||
* **Update**: `engineering/infra/containers.md` — marked `podman generate systemd` deprecated (podman 5.7), documented Quadlet with a field-tested gotcha list (default network DNS off, `[Service] EnvironmentFile=` for `${VAR}` expansion, unit naming, bind-mount UID mapping).
|
||||
## 2026-08-11 — Engineering research area; skills leaderboard verified
|
||||
|
||||
## 2026-08-13
|
||||
Created `engineering/` (SDLC, agent instruction files, stacks, infra,
|
||||
plugins, skills ecosystem, Signal remote) via parallel research fleet.
|
||||
Skills leaderboard replaced with the ranked list from the skills.sh API
|
||||
(zero-based pagination, 200-skill pages).
|
||||
|
||||
### Pi Subagents Limits
|
||||
## 2026-08-11 — Agentic web research section; exhaustive bundle audit
|
||||
|
||||
* Added a "Parallel Execution and Limits" section to `pi/packages/pi-subagents.md`.
|
||||
* Documented the effective values: `globalConcurrencyLimit` 2 (from `extensions/subagent/config.json`), `parallel.maxTasks` 8, `parallel.concurrency` 4, `maxSubagentSpawnsPerSession` unlimited, `maxSubagentDepth` 2, and `turnBudget.maxTurns` 30.
|
||||
* Noted that no per-model limit exists; all caps are global to a run or a session.
|
||||
Created `agentic-web-research/` (8 pages) and rewrote them on 2025/2026
|
||||
evidence (SearXNG valkey deployment, real engine defaults, limiter budgets,
|
||||
Gluetun pattern, open-model claim triage, MCP transports). Audit: 154+
|
||||
wikilinks resolved, dead external links fixed, `MemorySleepMode=deep`
|
||||
verified valid (systemd 256+), ASD-STE100 style pass. `AGENTS.md` created as
|
||||
the system behavior contract.
|
||||
|
||||
## 2026-08-11 (continued)
|
||||
## 2026-08-06 — Link fixes; ComfyUI docs; major documentation overhaul
|
||||
|
||||
### Engineering Research — New Area
|
||||
Fixed 15 broken wikilinks (missing frontmatter) + title mismatches → zero
|
||||
broken. Added ComfyUI pages, per-host system docs, pi config tree, tools
|
||||
entries; orphaned root duplicates moved to `.AGENTTRASH/`.
|
||||
|
||||
* Created the `engineering/` research area: SDLC and tooling, agent instruction files, language and framework stacks, infrastructure and cloud, pi plugins, skills ecosystem, and Signal remote control.
|
||||
* Ran a parallel research fleet (scout + 6 researchers) grounded in current 2025/2026 web sources.
|
||||
## 2026-07-18 — Maintenance tooling
|
||||
|
||||
### Skills Leaderboard — Live Verification
|
||||
Expanded `references/okf-maintenance.md` (cross-links, health metrics,
|
||||
troubleshooting); created `core/log.md` and `.okf/config.yaml`.
|
||||
|
||||
* Queried the skills.sh API (`GET /api/skills/all-time/{page}`) for the authoritative top 50 skills by all-time installs.
|
||||
* Replaced the inferred category table in `engineering/skills-ecosystem.md` with the verified ranked list.
|
||||
* Noted the API’s zero-based pagination and 200-skill page size for future queries.
|
||||
## 2026-01-15 — OKF conversion
|
||||
|
||||
## 2026-08-11 (continued)
|
||||
|
||||
### Agentic Web Research — Grounded Revision
|
||||
|
||||
* Ran a parallel research fleet (7 researchers + 2 scouts) for current 2025-2026 evidence on SearXNG tuning, VPN split-routing, agentic search, open models, research orchestration, and MCP.
|
||||
* Rewrote all 8 `agentic-web-research/` pages to match verified facts and the local topology: SearXNG at `192.168.0.235:8081`, llama.cpp inference on `7770` (dankserver/dankclaw) and `8080` (local-ornith), main model `openrouter/deepseek-v4-flash-0731`.
|
||||
* SearXNG: corrected to Valkey deployment, real engine defaults (DuckDuckGo/Wikipedia/Google News active, Google inactive, Bing disabled), limiter budgets, current `outgoing` defaults.
|
||||
* VPN: added Gluetun as the recommended pattern, corrected OpenVPN container joins, added `source_ips`/`network: ipv4`.
|
||||
* Open models: clarified Llama 4 claims (10M ctx = Scout only, single-H100 needs INT4, "beats GPT-4o" is Meta-only), added Qwen2.5-VL-7B as best self-hostable vision model.
|
||||
* Web agents: corrected the Browser Use "87.4%" claim (managed Cloud variant, not open-source; peer-reviewed 44.5% for CUA), added Skyvern.
|
||||
* MCP: updated transports (stdio + Streamable HTTP, legacy SSE), current reference servers, added SearXNG MCP, tightened security rules.
|
||||
|
||||
### Exhaustive Bundle Audit
|
||||
|
||||
* Link audit: resolved all 154+ wikilinks by frontmatter title — **0 broken wikilinks**. Fixed relative-link base errors in `core/index-doc.md`, `packages/index.md`, `pi-web-access.md`, `llama-cpp/setup.md`, `npx-skills/skill-commands.md`, `packages/pi-browser-use/index.md`.
|
||||
* External URL audit: fixed dead links (SearXNG limiter path, earendil-works/pi blob URLs, AYayOS/qs -> outfoxxed/quickshell, badlogic/pi-mono -> earendil-works/pi).
|
||||
* Factual fixes: `core/settings.md` stale JSON (defaultProvider/model/thinkingLevel/changelog-version), `pi/models.md` dankclaw auth, `Sleep-Fix-Guide.md` kernel 7.1.3 -> 7.1.4.
|
||||
* Verified (did not change) `MemorySleepMode=deep`: it is a valid systemd 256+ option.
|
||||
* ASD-STE100 style pass: removed contractions, banned `may`, and prose semicolons across research/tools/pi docs.
|
||||
* Added OKF index frontmatter to `core/index.md` and `skills/index.md`.
|
||||
* Added a "Pi-peon is installed" note to the npx skills ecosystem table and a port-7770 system note to llama.cpp docs.
|
||||
|
||||
### Agentic Web Research Section
|
||||
|
||||
* Created `agentic-web-research/` — seven new concept pages plus index covering self-hosted web agents, SearXNG tuning, VPN routing, agentic search practices, open models, research effectiveness, and model context protocol.
|
||||
* Expanded via parallel research: concrete BM25/Pruning/LLM content filters, credibility heuristics, failure-mode guardrails, MCP server and transport guidance.
|
||||
* Added the section to `index.md` under a new `## [Agentic Web Research]` heading.
|
||||
* Linked `pi/packages/pi-web-access.md` to the new section.
|
||||
|
||||
### System Instruction File
|
||||
|
||||
* Created `AGENTS.md` — system behavior contract with a dedicated layer on parallel subagent execution (one `subagent` call with `tasks` + `concurrency`).
|
||||
|
||||
### Bundle Audit
|
||||
|
||||
* Verified all 154 wikilinks resolve (zero broken).
|
||||
* Removed stale empty `Alienware M16a2 Sleep/Wake Issues.md` duplicate into `.AGENTTRASH`.
|
||||
* ran ASD-STE100 style pass: converted `should` to imperative or `must`, and `e.g.` to `for example` across 10 files.
|
||||
* Removed stale `frank-default-omni` model references and corrected dankclaw port `13305` to `8080` per commit `15d4af4`.
|
||||
* **Resolved**: the live config is authoritative. Updated both llama.cpp servers to port `7770` and set the default provider to `openrouter` (deepseek) per `settings.json`. Dankserver/dankclaw now 7770; main session default is openrouter.
|
||||
|
||||
## 2026-08-06 (continued)
|
||||
|
||||
### Link Fixes
|
||||
|
||||
* Fixed 15 broken wikilinks — added missing YAML frontmatter to `ghostty/index.md`, `tmux/index.md`, `linux-power-management/index.md`, `gitea/index.md`, `gitea/architecture.md`, `gitea/data-persistence.md`, `gitea/management.md`
|
||||
* Fixed title mismatches: `OKF v0.1 Specification` → `Open Knowledge Format (OKF) v0.1 Specification`, `Pi Settings` → `Pi Settings System (settings.json)`, `Alienware M16a2 Sleep/Wake Issues` → `Alienware M16a2 Linux Sleep/Wake Issues`, `Architecture Details` → `Gitea Architecture`, `Data Persistence` → `Gitea Data Persistence`, `Management Guide` → `Gitea Management`
|
||||
* Zero broken links remaining (47 links verified)
|
||||
|
||||
## 2026-08-06
|
||||
|
||||
### ComfyUI Documentation
|
||||
|
||||
* `tools/comfyui/index.md` — ComfyUI setup on dankclaw, architecture, service management
|
||||
* `tools/comfyui/troubleshooting.md` — Common errors, diagnostics, recovery steps
|
||||
* `tools/index.md` — Added ComfyUI entry
|
||||
* `system/dankclaw.md` — Added ComfyUI service, hardware specs, services section
|
||||
|
||||
### Major Documentation Overhaul
|
||||
|
||||
**Created — System Documentation**
|
||||
|
||||
* `system/index.md` — System documentation index with infrastructure diagram
|
||||
* Per-host system pages (overview, hardware specifications, display configuration, network interfaces) for the workstation — retired later; see `/system/network.md` and `/tools/niri/displays.md`
|
||||
* `system/dankserver.md` — Primary llama.cpp server documentation
|
||||
* `system/dankclaw.md` — Secondary llama.cpp server documentation
|
||||
|
||||
**Created — Pi Configuration**
|
||||
|
||||
* `pi/index.md` — Pi configuration overview with architecture diagram
|
||||
* `pi/settings.md` — Main settings.json reference (moved from core/)
|
||||
* `pi/models.md` — models.json provider and model definitions
|
||||
* `pi/packages/index.md` — Installed packages index
|
||||
* `pi/packages/pi-peon.md` — CESP/OpenPeon sound-pack player
|
||||
* `pi/packages/pi-web-access.md` — Web search, fetching, video understanding
|
||||
* `pi/packages/pi-subagents.md` — Core subagent delegation
|
||||
* `pi/skills/index.md` — Installed agent skills inventory
|
||||
|
||||
**Created — Tools**
|
||||
|
||||
* `tools/cachyos/index.md` — CachyOS documentation (kernel, repos, gaming stack)
|
||||
* `tools/noctalia-shell/index.md` — Noctalia Shell with Niri integration
|
||||
* `tools/applications/index.md` — Default applications reference
|
||||
|
||||
**Updated**
|
||||
|
||||
* `core/settings.md` — Updated with current config, subagent overrides, cross-links
|
||||
* `tools/niri/index.md` — Rewritten with actual system configuration
|
||||
* `tools/index.md` — Added CachyOS, Noctalia, Applications entries
|
||||
* `index.md` — Complete rewrite with new sections and cross-links
|
||||
|
||||
**Moved / Cleaned**
|
||||
|
||||
* `tmux.md` → `tools/tmux/index.md`
|
||||
* Orphaned root duplicates → `.AGENTTRASH/` (npx-skills.md, okf-maintenance.md, okf-spec.md, vercel-labs-skills.md, vercel-labs-skills-find-skills.md, ornith-llama-cpp-setup.md)
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-18
|
||||
|
||||
* **Enhancement**: Expanded `okf-maintenance.md` — added cross-link management, index management, health metrics, troubleshooting, and quick reference card
|
||||
* **Creation**: `core/log.md` — change log for the core documentation directory
|
||||
* **Creation**: `.okf/config.yaml` — bundle tooling configuration
|
||||
* **Update**: `core/index.md` — added log.md entry and cross-references
|
||||
|
||||
## 2026-01-15
|
||||
|
||||
* **Initialization**: Converted docs bundle to OKF v0.1 format
|
||||
* **Migration**: Migrated files to `core/`, `tools/`, `packages/`, `references/` directories
|
||||
* **Applied**: OKF frontmatter to all files
|
||||
Docs bundle converted to OKF v0.1; files migrated into `core/`, `tools/`,
|
||||
`packages/`, `references/` with frontmatter on all files.
|
||||
|
||||
## 2025-08-05 — Gitea documentation
|
||||
|
||||
Added ](tools/gitea/index.md) documentation to tools. Covers:
|
||||
|
||||
* [[architecture|architecture]] — Container topology, Caddy reverse proxy, network diagram.
|
||||
* [[management|management]] — Podman commands, upgrades, troubleshooting.
|
||||
* [[data-persistence|data-persistence]] — Volume mounts, backup strategy, restore procedures.
|
||||
|
||||
Updated tools index.
|
||||
Added [tools/gitea/index.md](tools/gitea/index.md) (topology, management,
|
||||
data persistence) to the tools index.
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
# Pi Packages
|
||||
|
||||
Self-contained extensions and tools bundled as npm packages, distributed via the `pi install` system. Each package contains extensions, skills, prompts, or themes.
|
||||
|
||||
---
|
||||
|
||||
## Concept Files
|
||||
|
||||
* [pi-browser-use](pi-browser-use.md) — Browser automation extension wrapping chrome-devtools-mcp with `browser_` prefix, full config reference, session modes, and vision model setup.
|
||||
* [pi-permission-system](pi-permission-system.md) — Permission enforcement and policy configuration system with 10 interconnected docs.
|
||||
|
||||
## Cross-References
|
||||
|
||||
- All packages are installed via `pi install npm:<name>` and loaded by pi's extension system.
|
||||
- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution mechanism and package.json manifest format.
|
||||
+18
-32
@@ -1,37 +1,28 @@
|
||||
# Pi Configuration
|
||||
# Pi Configuration (archive)
|
||||
|
||||
> **Archive note (2026-10-18).** Most pages in this directory document the retired
|
||||
> **pi** harness (settings.json / models.json, `frank-default-*` endpoints, verified
|
||||
> 2026-08-28). The live harness is **omp** — its config is `agent/config.yml` +
|
||||
> `agent/models.yml` in this repo, the current fleet endpoints are on
|
||||
> [System hosts](/system/index.md), and omp-specific knowledge lands in pages like
|
||||
> [OMP Status Line Customization](/pi/statusline.md) below. Read pi pages as
|
||||
> historical records, not current state.
|
||||
> **Archive (2026-10-18).** This directory documents the retired **pi** harness
|
||||
> (`settings.json` / `models.json`, `frank-default-*` endpoints). The live
|
||||
> harness is **omp**: config in `agent/config.yml` + `agent/models.yml` (this
|
||||
> repo), fleet endpoints on [System hosts](/system/index.md). Read these pages
|
||||
> as historical records, not current state. Knowledge that survived the harness
|
||||
> move lives under [Core](/core/index.md):
|
||||
> [OMP Status Line](/core/statusline.md) and
|
||||
> [OMP Subagent Limits](/core/subagent-limits.md).
|
||||
|
||||
## Configuration Files
|
||||
## Configuration Files (pi-era)
|
||||
|
||||
- [Pi Settings System (settings.json)](/core/settings.md) — Main `settings.json` reference. Providers, models, packages, subagent overrides.
|
||||
- [Pi Models Configuration](/pi/models.md) — `models.json` reference. Provider definitions, model specs, endpoints.
|
||||
- [OMP Status Line Customization](/pi/statusline.md) — How presets, composer shapes, and segment arrays actually interact; the fleet's tuned bar.
|
||||
- [Pi Settings System (settings.json)](/core/settings.md) — Main `settings.json` record. Providers, models, packages, subagent overrides.
|
||||
- [Pi Models Configuration](/pi/models.md) — `models.json` record. Provider definitions, model specs, endpoints.
|
||||
|
||||
## Extensions
|
||||
## Extensions (pi-era)
|
||||
|
||||
- [Pi Packages](/pi/packages/index.md) — Installed npm packages that extend pi functionality.
|
||||
- [Pi Peon](/pi/packages/pi-peon.md) — CESP/OpenPeon sound-pack player for lifecycle events.
|
||||
- [Pi Web Access](/pi/packages/pi-web-access.md) — Web search, URL fetching, GitHub cloning, PDF extraction, video understanding.
|
||||
- [Pi Browser Use](/packages/pi-browser-use.md) — Browser automation extension wrapping chrome-devtools-mcp with a `browser_` prefix.
|
||||
- [Pi Permission System](/packages/pi-permission-system.md) — Permission enforcement and policy configuration for subagent extensions.
|
||||
- [Pi Packages](/pi/packages/index.md) — installed npm packages: peon, web-access, subagents, browser-use, permission-system.
|
||||
|
||||
## Skills
|
||||
## Skills (pi-era)
|
||||
|
||||
- [Pi Skills](/pi/skills.md) — Installed agent skills. Symlinked from `~/.agents/skills/` and `~/.pi/agent/skills/`.
|
||||
- [Pi Skills](/pi/skills.md) — installed skills inventory. Current skill toolchain: [Skills](/skills/index.md).
|
||||
|
||||
## Subagent Architecture
|
||||
|
||||
- [OMP Subagent Limits & Fan-out Policy](/pi/subagent-limits.md) — Live caps: concurrency 2, no nested spawns (and the `maxRecursionDepth: 0` trap), per-endpoint in-flight ceilings, isolation policy.
|
||||
- [Pi Subagents](/pi/packages/pi-subagents.md) — (historical) pi-era delegation system. Chains, parallel execution, TUI clarification.
|
||||
|
||||
## Architecture
|
||||
## Architecture (pi-era)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
@@ -51,7 +42,7 @@ graph TD
|
||||
M --> O[dankclaw 192.168.0.143:7770]
|
||||
```
|
||||
|
||||
## Note on the Live Default
|
||||
## Note on the Live Default (historical)
|
||||
|
||||
In the pi era, `models.json` defined the live provider set: the main session
|
||||
provider was `llamacpp` with default model `frank-default-large` (Dankclaw);
|
||||
@@ -60,8 +51,3 @@ to `frank-default-large`. Two scopes owned settings: the user
|
||||
`~/.pi/settings.json` (main → Dankclaw/large) and the project
|
||||
`/home/dank/.pi/agent/settings.json` (main → Dankserver/small); when they
|
||||
disagreed, the project-scope file won for the agent's own main session.
|
||||
|
||||
> **Note:** This documentation describes the pi-coding-agent harness (config
|
||||
> format, packages, skill system) as general reference material. The live
|
||||
> harness is OMP at `~/.omp/`; OMP-managed skills live in
|
||||
> `~/.omp/agent/managed-skills/`.
|
||||
|
||||
@@ -145,4 +145,3 @@ The subagent model IDs (`frank-default-small`, `frank-default-large`) resolve ag
|
||||
- [[settings|settings]] — Main configuration file
|
||||
- [[dankserver|dankserver]] — Primary llama.cpp server
|
||||
- [[dankclaw|dankclaw]] — Secondary llama.cpp server
|
||||
- [ornith-llama-cpp-setup](../tools/ornith-llama-cpp-setup/index.md) — Local Ornith model setup
|
||||
|
||||
@@ -1,29 +1,27 @@
|
||||
# Pi Packages
|
||||
|
||||
Pi extends its functionality through npm packages installed via `pi install`. Each package provides extensions, skills, prompts, or themes.
|
||||
Pi extended itself through npm packages (`pi install npm:<name>`), each
|
||||
bundling extensions, skills, prompts, or themes. The harness is retired
|
||||
(2026-10-18); this page is the merged census of what was installed — one row
|
||||
per package, detail pages kept as historical records.
|
||||
|
||||
## Installed Packages
|
||||
## Installed packages
|
||||
|
||||
| Package | Version | Description |
|
||||
|---------|---------|-------------|
|
||||
| [[pi-peon|pi-peon]] | 0.1.1 | CESP/OpenPeon sound-pack player for pi lifecycle events |
|
||||
| [[pi-web-access|pi-web-access]] | 0.22.0 | Web search, URL fetching, GitHub cloning, PDF extraction, video understanding |
|
||||
| Package | Version | Detail | What it did |
|
||||
|---------|---------|--------|-------------|
|
||||
| `@wierdbytes/pi-peon` | 0.1.1 | [Pi Peon](pi-peon.md) | CESP/OpenPeon sound-pack player for pi lifecycle events. |
|
||||
| `pi-web-access` | 0.22.0 | [Pi Web Access](pi-web-access.md) | Web search, URL fetching, GitHub cloning, PDF extraction, video understanding. |
|
||||
| `pi-subagents` | 0.36.0 | [Pi Subagents](pi-subagents.md) | Core subagent delegation — chains, parallel execution, TUI clarification. |
|
||||
| `pi-browser-use` | — | [Pi Browser Use](pi-browser-use.md) | Browser automation wrapping chrome-devtools-mcp behind a `browser_` prefix. |
|
||||
| `pi-permission-system` | — | [Pi Permission System](pi-permission-system.md) | Permission enforcement and policy configuration; upstream docs are 10 interlinked pages. |
|
||||
|
||||
## Core Extension
|
||||
## Where the concepts live now
|
||||
|
||||
| Package | Version | Description |
|
||||
|---------|---------|-------------|
|
||||
| [[pi-subagents|pi-subagents]] | 0.36.0 | Core subagent delegation — chains, parallel execution, TUI clarification |
|
||||
|
||||
---
|
||||
* Subagent delegation → [OMP Subagent Limits & Fan-out Policy](/core/subagent-limits.md) (live caps).
|
||||
* Skill/package distribution → [Skills](/skills/index.md) (Agent Skills standard + `skills` CLI).
|
||||
* Web access → the `web/searxng` provider and MCP tooling; see [Agentic web research](/agentic-web-research/index.md).
|
||||
|
||||
## See Also
|
||||
|
||||
- [[settings|settings]] — Package configuration in settings.json
|
||||
- [pi](../index.md) — Pi configuration overview
|
||||
|
||||
* [Pi Peon](pi-peon.md) — CESP/OpenPeon sound-pack player for pi lifecycle events — peons, GLaDOS, battlecruisers, and 300+ community sound packs.
|
||||
|
||||
* [Pi Subagents](pi-subagents.md) — Core pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification.
|
||||
|
||||
* [Pi Web Access](pi-web-access.md) — Web search, URL fetching, GitHub cloning, PDF extraction, and video understanding for Pi. Zero-config with Exa MCP.
|
||||
- [Pi Settings System](/core/settings.md) — where these packages were registered (`settings.json` archive).
|
||||
- [Pi Configuration](/pi/index.md) — pi-era overview.
|
||||
|
||||
@@ -113,5 +113,5 @@ Resolves API key and base URL from the model registry automatically.
|
||||
|
||||
## Cross-References
|
||||
|
||||
- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution system.
|
||||
- See [OKF Specification](../references/okf-spec.md) for the knowledge bundle format.
|
||||
- See [Skills](/skills/index.md) for the skill toolchain that replaced pi-package distribution.
|
||||
- See [OKF Specification](/references/okf-spec.md) for the knowledge bundle format.
|
||||
@@ -81,5 +81,5 @@ The `/peon` command opens an interactive settings modal with:
|
||||
|
||||
## See Also
|
||||
|
||||
- [packages](../../packages/index.md) — Package overview
|
||||
- [Pi Packages](index.md) — Package overview
|
||||
- [pi](../index.md) — Pi configuration
|
||||
|
||||
+2
-2
@@ -33,5 +33,5 @@ timestamp: 2026-08-28
|
||||
|
||||
## Cross-References
|
||||
|
||||
- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution system.
|
||||
- See [AGENTS.md Format](../core/agents-md-format.md) for the system-level instruction format that governs how this system is referenced in agent contracts.
|
||||
- See [Skills](/skills/index.md) for the skill toolchain that replaced pi-package distribution.
|
||||
- See [AGENTS.md Format](/core/agents-md-format.md) for the system-level instruction format that governs how this system is referenced in agent contracts.
|
||||
@@ -44,4 +44,4 @@ Agent skills teach the agent new workflows. Skills are stored in `~/.pi/agent/sk
|
||||
## See Also
|
||||
|
||||
- [pi](index.md) — Pi configuration overview
|
||||
- [[npx-skills|npx-skills]] — Skill distribution via npm
|
||||
- [Skills documentation](../skills/index.md) — the standard, CLI, and store wiring (current harness)
|
||||
|
||||
@@ -8,11 +8,20 @@ tags:
|
||||
- documentation
|
||||
- knowledge-bundle
|
||||
- specification
|
||||
verified: 2026-08-28
|
||||
verified: 2026-10-19
|
||||
timestamp: 2026-01-15
|
||||
---
|
||||
|
||||
> **Note:** Google Cloud published OKF v0.2 at [GoogleCloudPlatform/open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format) with additional frontmatter families for provenance, trust, and attestation. This document covers the v0.1 format used by this knowledge bundle.
|
||||
> **Note:** Google Cloud published OKF v0.2 at
|
||||
> [GoogleCloudPlatform/open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format)
|
||||
> (SPEC.md, verified 2026-10-19). v0.2 is a minor bump with two deliberate
|
||||
> breaking changes: `timestamp` is superseded by `generated: { by, at }`, and the
|
||||
> body `# Citations` list is superseded by a `sources` frontmatter family; it adds
|
||||
> optional trust/lifecycle fields (`verified: { by, at }`, `status`,
|
||||
> `stale_after`) and the `Attested Computation` type, and permits `okf_version:`
|
||||
> frontmatter in a bundle-root `index.md`. This bundle stays on v0.1 semantics
|
||||
> (kb-lint enforces them); the bundle-local `verified:` date stamp and `tags`
|
||||
> discipline are producer extensions compatible with both versions.
|
||||
|
||||
# Open Knowledge Format (OKF) v0.1
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
type: reference
|
||||
title: Alienware M16a2 Linux Sleep/Wake Issues
|
||||
description: Comprehensive research on NVIDIA GPU driver state corruption during suspend/resume on Alienware M16a2 with Linux.
|
||||
description: "Sleep/wake research on the Alienware m16 R2 (dankware, sold 2026-09-28): NVIDIA driver state corruption during suspend/resume on Dell hardware. Kept as class-level Dell/Alienware + NVIDIA knowledge."
|
||||
tags:
|
||||
- research
|
||||
- sleep-wake
|
||||
@@ -12,6 +12,13 @@ timestamp: 2026-01-15
|
||||
|
||||
# Alienware M16a2 Linux Sleep/Wake Issues — Comprehensive Research
|
||||
|
||||
> **Machine archive (2026-10-19).** "This system" throughout is **dankware**,
|
||||
> the Alienware m16 R2 client workstation sold 2026-09-28 (see `log.md`). The
|
||||
> current dev workstation (`blankpad` — AMD Ryzen 5 PRO 5650U / Cezanne APU,
|
||||
> s2idle only, no NVIDIA GPU) is not this machine. Hardware inventory and
|
||||
> driver versions are historical; the class-level Dell/Alienware + NVIDIA
|
||||
> suspend research is retained as durable knowledge.
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The symptom — **screen stays black after waking from sleep (lid close)** — is a well-documented class of issues on Dell/Alienware laptops with NVIDIA GPUs running Linux. The root cause is almost always **NVIDIA GPU driver state corruption during suspend/resume**, compounded by ACPI/sleep state selection issues and BIOS/firmware settings.
|
||||
@@ -21,7 +28,7 @@ The symptom — **screen stays black after waking from sleep (lid close)** — i
|
||||
## 1. Known Issues with Alienware M16a2 + Linux Sleep States
|
||||
|
||||
### 1.1 Model Context
|
||||
The Alienware m16 R2 (this system) is equipped with:
|
||||
The Alienware m16 R2 (the retired **dankware** box) is equipped with:
|
||||
- **Intel Core Ultra 7 155H** (Meteor Lake, 6p+8e cores, 22 threads)
|
||||
- **Intel Arc Graphics** (Meteor Lake-P iGPU)
|
||||
- **NVIDIA GeForce RTX 4070 Laptop GPU** (AD106M, Max-Q/Mobile)
|
||||
|
||||
@@ -1,312 +0,0 @@
|
||||
---
|
||||
type: guide
|
||||
title: Sleep Fix Guide
|
||||
description: Fix guide for Alienware M16a2 sleep/wake issues on CachyOS with NVIDIA RTX 40-series GPU.
|
||||
tags:
|
||||
- research
|
||||
- sleep-wake
|
||||
- fix
|
||||
- nvidia
|
||||
timestamp: 2026-01-15
|
||||
---
|
||||
z
|
||||
# Alienware M16a2 Sleep/Wake Fix Guide
|
||||
|
||||
Based on diagnostics from your system (CachyOS, Kernel 7.1.4, NVIDIA RTX 40-series)
|
||||
|
||||
---
|
||||
|
||||
## Problem Summary
|
||||
|
||||
Your system enters sleep when closing the lid, but the screen stays black on wake. Diagnostics show:
|
||||
- **Sleep state:** s2idle (Modern Standby) - problematic for NVIDIA hybrid GPUs
|
||||
- **NVIDIA services:** Disabled (nvidia-suspend.service, nvidia-resume.service)
|
||||
- **Kernel errors:** ACPI D-Notifier failures, spd5118 resume errors
|
||||
|
||||
---
|
||||
|
||||
## Fix #1: Enable NVIDIA Suspend Services (⚠️ MOST IMPORTANT)
|
||||
|
||||
This is the #1 cause of your issue. The NVIDIA GPU state is not being preserved during suspend.
|
||||
|
||||
```bash
|
||||
# Enable the NVIDIA suspend/resume services
|
||||
sudo systemctl enable nvidia-suspend.service
|
||||
sudo systemctl enable nvidia-resume.service
|
||||
|
||||
# Verify they're enabled
|
||||
systemctl status nvidia-suspend.service nvidia-resume.service
|
||||
```
|
||||
|
||||
**Deterministic verification:**
|
||||
```bash
|
||||
# This shows "enabled" for both services when the fixes work
|
||||
systemctl is-enabled nvidia-suspend.service nvidia-resume.service
|
||||
# Expected output: enabled\nenabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fix #2: Force S3 Deep Sleep (If Available)
|
||||
|
||||
s2idle is fundamentally broken for NVIDIA hybrid GPUs. Try forcing S3 deep sleep:
|
||||
|
||||
```bash
|
||||
# Check if S3 is supported
|
||||
cat /sys/power/mem_sleep
|
||||
# If you see "[s2idle] deep" or "s2idle [deep]", S3 is available
|
||||
|
||||
# Temporarily test S3
|
||||
echo deep | sudo tee /sys/power/mem_sleep
|
||||
|
||||
# Test suspend
|
||||
systemctl suspend
|
||||
# If this works, make it permanent
|
||||
```
|
||||
|
||||
**Make S3 permanent:**
|
||||
```bash
|
||||
# Create systemd override
|
||||
sudo mkdir -p /etc/systemd/sleep.d
|
||||
sudo tee /etc/systemd/sleep.d/deep-sleep.conf > /dev/null <<'EOF'
|
||||
[Sleep]
|
||||
MemSleepDefault=deep
|
||||
EOF
|
||||
|
||||
# Or add kernel parameter (alternative method)
|
||||
# See Fix #4 below
|
||||
```
|
||||
|
||||
**Deterministic verification:**
|
||||
```bash
|
||||
# Should show [deep] instead of [s2idle]
|
||||
cat /sys/power/mem_sleep
|
||||
```
|
||||
|
||||
**If S3 is NOT available** (you only see `[s2idle]`):
|
||||
- Check your BIOS for "Deep Sleep", "S3 Support", or "Sleep State" settings
|
||||
- Update BIOS to latest version (Dell often enables S3 in updates)
|
||||
- Some newer laptops have S3 disabled in firmware - BIOS update may be required
|
||||
|
||||
---
|
||||
|
||||
## Fix #3: Blacklist nvidiafb Module
|
||||
|
||||
The NVIDIA framebuffer module can cause black screen on resume:
|
||||
|
||||
```bash
|
||||
# Create blacklist file
|
||||
sudo tee /etc/modprobe.d/blacklist-nvidiafb.conf > /dev/null <<'EOF'
|
||||
blacklist nvidiafb
|
||||
EOF
|
||||
|
||||
# Regenerate initramfs
|
||||
sudo mkinitcpio -P
|
||||
|
||||
# Verify nvidiafb is not loaded
|
||||
lsmod | grep nvidiafb
|
||||
# Expected: no output
|
||||
```
|
||||
|
||||
**Deterministic verification:**
|
||||
```bash
|
||||
# Should return non-zero (module not found)
|
||||
lsmod | grep -q nvidiafb && echo "FAIL: nvidiafb loaded" || echo "PASS: nvidiafb not loaded"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fix #4: Add Kernel Parameters
|
||||
|
||||
Add these parameters to improve ACPI and sleep behavior:
|
||||
|
||||
```bash
|
||||
# For GRUB (edit /etc/default/grub):
|
||||
# GRUB_CMDLINE_LINUX_DEFAULT="... mem_sleep_default=deep acpi_backlight=vendor"
|
||||
|
||||
# For systemd-boot (edit /boot/loader/entries/*.conf):
|
||||
# Add to options line: mem_sleep_default=deep acpi_backlight=vendor
|
||||
|
||||
# For your current setup (check your bootloader):
|
||||
# Add these parameters:
|
||||
# mem_sleep_default=deep - forces S3 if available
|
||||
# acpi_backlight=vendor - fixes backlight control on resume
|
||||
# acpi_enforce_resources=lax - allows ACPI resource access
|
||||
```
|
||||
|
||||
After editing bootloader config:
|
||||
```bash
|
||||
# GRUB
|
||||
sudo update-grub
|
||||
|
||||
# systemd-boot - no action needed, changes take effect on next boot
|
||||
```
|
||||
|
||||
**Deterministic verification:**
|
||||
```bash
|
||||
# Check if parameters are active
|
||||
cat /proc/cmdline | grep -E "mem_sleep_default|acpi_backlight"
|
||||
# Should show the parameters you added
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fix #5: Disable Problematic Wake Sources
|
||||
|
||||
Your diagnostics show XHCI (USB) and RP01/RP05 (PCIe) wake sources enabled. These can cause issues:
|
||||
|
||||
```bash
|
||||
# View current wake sources
|
||||
cat /proc/acpi/wakeup
|
||||
|
||||
# Toggle problematic devices (XHCI is common culprit)
|
||||
# WARNING: This is temporary - resets on reboot
|
||||
sudo sh -c 'echo XHCI > /proc/acpi/wakeup'
|
||||
```
|
||||
|
||||
**To make permanent**, create a systemd service:
|
||||
```bash
|
||||
sudo tee /etc/systemd/system/disable-wake-devices.service > /dev/null <<'EOF'
|
||||
[Unit]
|
||||
Description=Disable problematic wake devices
|
||||
Before=sleep.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/bin/sh -c 'echo XHCI > /proc/acpi/wakeup'
|
||||
ExecStart=/bin/sh -c 'echo RP01 > /proc/acpi/wakeup'
|
||||
ExecStart=/bin/sh -c 'echo RP05 > /proc/acpi/wakeup'
|
||||
|
||||
[Install]
|
||||
WantedBy=sleep.target
|
||||
EOF
|
||||
|
||||
sudo systemctl enable disable-wake-devices.service
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fix #6: Update BIOS/Firmware
|
||||
|
||||
Dell frequently releases BIOS updates that fix ACPI/suspend bugs:
|
||||
|
||||
```bash
|
||||
# Check for firmware updates
|
||||
sudo fwupdmgr get-updates
|
||||
|
||||
# If updates available:
|
||||
sudo fwupdmgr update
|
||||
```
|
||||
|
||||
**Deterministic verification:**
|
||||
```bash
|
||||
# Check current BIOS version
|
||||
dmidecode -s bios-version
|
||||
dmidecode -s bios-release-date
|
||||
# Compare with Dell support site for your M16a2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fix #7: Configure TLP (If Installed)
|
||||
|
||||
If you use TLP for power management, add these settings:
|
||||
|
||||
```bash
|
||||
sudo tee -a /etc/tlp.conf > /dev/null <<'EOF'
|
||||
# NVIDIA power management
|
||||
RUNTIME_PM_ON_AUTO_SUSPEND=auto
|
||||
RUNTIME_PM_ON_IDLE_THRESHOLD=30
|
||||
|
||||
# PCI Express ASPM
|
||||
PCIE_ASPM_ON_AC=powersupersave
|
||||
PCIE_ASPM_ON_BAT=powersupersave
|
||||
EOF
|
||||
|
||||
# Restart TLP
|
||||
sudo tlp start
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Procedure
|
||||
|
||||
After applying fixes, test in this order:
|
||||
|
||||
### Test 1: Manual Suspend
|
||||
```bash
|
||||
# Simple suspend test
|
||||
systemctl suspend
|
||||
# Expected: System sleeps, wakes properly when you press a key/move mouse
|
||||
```
|
||||
|
||||
### Test 2: Lid Close Test
|
||||
```bash
|
||||
# Check lid trigger setting
|
||||
cat /etc/systemd/logind.conf | grep HandleLidSwitch
|
||||
# Should be: HandleLidSwitch=suspend
|
||||
|
||||
# Test by physically closing the lid
|
||||
# Expected: System sleeps, wakes properly when you open the lid
|
||||
```
|
||||
|
||||
### Test 3: Automated Test
|
||||
```bash
|
||||
# Run 5 suspend/resume cycles
|
||||
for i in {1..5}; do
|
||||
echo "Cycle $i"
|
||||
systemctl suspend
|
||||
# Wake up when system suspends
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Emergency Recovery
|
||||
|
||||
If you get a black screen after wake:
|
||||
|
||||
1. **Try switching TTY:** `Ctrl+Alt+F3` - if this works, it is a display issue
|
||||
2. **SSH into the machine** from another device and check logs
|
||||
3. **Hard reset:** Hold power button for 10 seconds
|
||||
4. **Check logs after reboot:**
|
||||
```bash
|
||||
journalctl -b -1 -k | grep -iE "suspend|resume|nvidia|acpi"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If a fix breaks something:
|
||||
|
||||
1. **NVIDIA services:** `sudo systemctl disable nvidia-suspend.service`
|
||||
2. **S3 sleep:** Remove the sleep.d config or kernel parameter
|
||||
3. **nvidiafb blacklist:** Remove `/etc/modprobe.d/blacklist-nvidiafb.conf` and regenerate initramfs
|
||||
4. **Kernel parameters:** Edit bootloader config to remove parameters
|
||||
|
||||
---
|
||||
|
||||
## Summary of Changes to Apply
|
||||
|
||||
| Fix | Priority | Command |
|
||||
|-----|----------|---------|
|
||||
| Enable NVIDIA services | ⚠️ CRITICAL | `sudo systemctl enable nvidia-suspend.service nvidia-resume.service` |
|
||||
| Blacklist nvidiafb | HIGH | Create `/etc/modprobe.d/blacklist-nvidiafb.conf` + `sudo mkinitcpio -P` |
|
||||
| Force S3 sleep | HIGH | `echo deep \| sudo tee /sys/power/mem_sleep` (test first) |
|
||||
| Kernel parameters | MEDIUM | Add `mem_sleep_default=deep acpi_backlight=vendor` to bootloader |
|
||||
| Update BIOS | MEDIUM | `sudo fwupdmgr get-updates` |
|
||||
| Disable wake sources | LOW | Create wake device toggle service |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Start with Fix #1** (enable NVIDIA services) - this is most likely the issue
|
||||
2. **Test suspend** after each fix
|
||||
3. **Apply Fix #2** if s2idle continues to fail
|
||||
4. **Apply Fix #3** (blacklist nvidiafb) - low risk, high reward
|
||||
5. **Consider Fix #4** (kernel parameters) if issues persist
|
||||
6. **Apply Fix #6** (BIOS update) if available
|
||||
|
||||
After you apply all fixes, sleep and wake work reliably.
|
||||
@@ -170,7 +170,7 @@ This allows plugging in any custom secrets backend.
|
||||
|
||||
— [Keychain and Windows Credentials Manager][keyring]
|
||||
|
||||
**This is relevant for the workstation** — CachyOS uses GNOME Keyring (KDE uses kwallet, but the system has GNOME components). On the Strix Halo (Arch Linux) and RTX 3090 (FreeToken) boxes, GNOME Keyring or kwallet would be available depending on desktop environment.
|
||||
**This is relevant for the workstation** — CachyOS uses GNOME Keyring (KDE uses kwallet, but the system has GNOME components). On the Ubuntu 26.04 server boxes (dankclaw, dankserver), GNOME Keyring or kwallet would be available depending on desktop environment.
|
||||
|
||||
---
|
||||
|
||||
@@ -336,9 +336,9 @@ Use symlinks for configs that external programs modify and must write back to (V
|
||||
|
||||
### Setup
|
||||
|
||||
- **Machine fleet:** the workstation (Intel Ultra 7, CachyOS, niri), dankclaw (Strix Halo, llama.cpp frank-default-large on port 7770), dankserver (RTX 3090, FreeToken, frank-default-small)
|
||||
- **Machine fleet:** the dev workstation (AMD Ryzen 5 PRO 5650U laptop, CachyOS, niri) plus client boxes; dankclaw (Strix Halo + RTX 3090, Ubuntu 26.04, fleet services); dankserver (2x Radeon AI PRO R9700, Ubuntu 26.04) — fleet detail: [/system/index.md](/system/index.md)
|
||||
- **Central config repo:** `~/.omp` — already a git repo with agent config, model manifests, and the KB
|
||||
- **OS mix:** All Linux, but different distros (CachyOS, Arch, custom FreeToken)
|
||||
- **OS mix:** All Linux, but different distros (CachyOS on clients, Ubuntu 26.04 LTS on both servers)
|
||||
|
||||
### Verdict: **Recommended with moderate reservations**
|
||||
|
||||
|
||||
@@ -1,18 +1,13 @@
|
||||
# Research Documentation
|
||||
|
||||
Hardware-specific research and fix guides.
|
||||
Research documents inform decisions and preserve class-level knowledge; they
|
||||
are not live state. Hardware pages describe machines the fleet has retired.
|
||||
|
||||
## Sleep/Wake Issues
|
||||
## Sleep/Wake Research
|
||||
|
||||
| File | Type | Description |
|
||||
|------|------|-------------|
|
||||
| [[Alienware-M16a2-Linux-sleep-wake-issues|Alienware-M16a2-Linux-sleep-wake-issues]] | research | Comprehensive research on NVIDIA GPU driver state corruption during suspend/resume on Alienware m16 R2 |
|
||||
| [[Sleep-Fix-Guide|Sleep-Fix-Guide]] | guide | Step-by-step fix guide for this system (CachyOS, Kernel 7.1.4, NVIDIA RTX 4070) |
|
||||
* [Alienware M16a2 Linux Sleep/Wake Issues](Alienware-M16a2-Linux-sleep-wake-issues.md) — NVIDIA suspend/resume corruption research on **dankware**, the Alienware m16 R2 workstation sold 2026-09-28. Retained as Dell/Alienware + NVIDIA class knowledge. General Linux sleep configuration lives in [Linux Power Management](../tools/linux-power-management.md).
|
||||
|
||||
* [Alienware M16a2 Linux Sleep/Wake Issues](Alienware-M16a2-Linux-sleep-wake-issues.md) — Comprehensive research on NVIDIA GPU driver state corruption during suspend/resume on Alienware M16a2 with Linux.
|
||||
|
||||
* [Sleep Fix Guide](Sleep-Fix-Guide.md) — Fix guide for Alienware M16a2 sleep/wake issues on CachyOS with NVIDIA RTX 40-series GPU.
|
||||
## Evaluations
|
||||
|
||||
* [Chezmoi Evaluation for Dotfiles Management](chezmoi-evaluation.md) — Evaluation of chezmoi (v2.72.0) as a dotfiles management tool for the workstation fleet.
|
||||
|
||||
* [Secrets Management for AI Agents in the Loop](secrets-for-agents.md) — Threat-modelled survey of secrets tools where agents have shell access and can read plaintext files and paste secrets into logs.
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
type: concept
|
||||
title: The Agent Skills Standard
|
||||
description: "The open Agent Skills standard: SKILL.md format, frontmatter fields, directory structure, progressive-disclosure loading, authoring practice, and how skills differ from extensions."
|
||||
tags:
|
||||
- skills
|
||||
- agent-skills
|
||||
- specification
|
||||
- authoring
|
||||
timestamp: 2026-10-19
|
||||
verified: 2026-10-19
|
||||
---
|
||||
|
||||
# The Agent Skills Standard
|
||||
|
||||
A **skill** is a directory containing a `SKILL.md` file: YAML frontmatter
|
||||
(`name` + `description`) followed by markdown instructions, plus optional
|
||||
`scripts/`, `references/`, and `assets/`. The standard is maintained at
|
||||
[agentskills.io](https://agentskills.io) and adopted by 79 coding agents
|
||||
(upstream agent registry, checked 2026-10-19), so one skill works across
|
||||
harnesses. The `skills` CLI installs them; see
|
||||
[Skills CLI](/skills/skills-cli.md).
|
||||
|
||||
## SKILL.md format
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What the skill does and when to use it.
|
||||
---
|
||||
|
||||
# My Skill
|
||||
Instructions the agent follows when the skill activates.
|
||||
```
|
||||
|
||||
### Frontmatter fields
|
||||
|
||||
| Field | Required | Notes |
|
||||
|-------|----------|-------|
|
||||
| `name` | yes | Max 64 chars; lowercase `a-z`, `0-9`, hyphens; no leading/trailing or consecutive hyphens (`pdf-processing` good, `PDF-Processing`, `-pdf`, `pdf--processing` bad). Pi does not require the name to match the parent directory; the standard does. |
|
||||
| `description` | yes | Max 1024 chars. The only text the agent sees when deciding whether to activate the skill. First sentence: what it does. Second: when to use it. |
|
||||
| `license` | no | License name or reference to a bundled file. |
|
||||
| `compatibility` | no | Max 500 chars; environment requirements. |
|
||||
| `metadata` | no | Arbitrary key/value mapping. `metadata.internal: true` hides the skill from discovery unless `INSTALL_INTERNAL_SKILLS=1` (skills CLI convention). |
|
||||
| `allowed-tools` | no | Space-delimited pre-approved tools (experimental; agent support varies — Zencoder and Kiro do not implement it). |
|
||||
| `disable-model-invocation` | no | When `true`, the skill is hidden from the system prompt; users invoke it explicitly (`/skill:name`). |
|
||||
|
||||
### Directory structure
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Required entry point
|
||||
├── scripts/ # Helper scripts (bash, js, python, ...)
|
||||
├── references/ # Detailed docs, loaded on demand
|
||||
├── assets/ # Templates, configs, binary data
|
||||
└── config.json # Optional skill settings
|
||||
```
|
||||
|
||||
Everything except `SKILL.md` is freeform. Scripts save tokens and improve
|
||||
reliability when the same code would otherwise be regenerated per run.
|
||||
|
||||
## Loading: progressive disclosure
|
||||
|
||||
Harnesses (pi, omp, Claude Code, ...) load skills the same way:
|
||||
|
||||
1. At startup, scan configured skill locations; extract `name` + `description` only.
|
||||
2. Inject the metadata list into the system prompt.
|
||||
3. On a matching task, the agent reads the full `SKILL.md` and follows it,
|
||||
referencing bundled scripts by relative path.
|
||||
|
||||
Only descriptions live in context permanently; full instructions load on demand.
|
||||
On omp the load order is priority-ranked: authored `agent/skills/` (100) beats
|
||||
the `~/.agents` store provider, which beats auto-learned
|
||||
`agent/managed-skills/` (5). See [Skill Store Wiring](/skills/store-wiring.md).
|
||||
|
||||
## Skills vs extensions
|
||||
|
||||
| | Skills | Extensions |
|
||||
|---|--------|------------|
|
||||
| Format | Markdown (`SKILL.md`) + scripts | TypeScript (`.ts`) |
|
||||
| Purpose | Instructions for the model | Code intercepting events, registering tools |
|
||||
| Execution | The agent reads and follows | Runs in the harness runtime |
|
||||
| Loading | On demand | Always loaded at startup |
|
||||
| Trust model | Review the text (it instructs the model) | Review the code (it executes) |
|
||||
|
||||
A harness package may bundle both (pi did; omp extensions live in
|
||||
`agent/extensions/`).
|
||||
|
||||
## Authoring practice
|
||||
|
||||
- Descriptions beat clever bodies: activation depends entirely on the description matching the user's words. "Extracts text and tables from PDF files, fills forms, merges documents" beats "Helps with PDFs."
|
||||
- Keep `SKILL.md` focused; push long detail into `references/` (files load whole; split past roughly 500 lines).
|
||||
- Skills instruct the model to run arbitrary commands, and scripts run with full user permissions. Review content before installing from untrusted sources.
|
||||
- Document dependencies (tools, API keys, setup steps) inside the skill.
|
||||
|
||||
## Citations
|
||||
|
||||
- [Agent Skills specification](https://agentskills.io) — re-fetched 2026-10-19.
|
||||
- [vercel-labs/skills README](https://github.com/vercel-labs/skills) — compatibility matrix, re-fetched 2026-10-19.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Skills CLI](/skills/skills-cli.md) — install/use/update tooling.
|
||||
- [Skill Store Wiring](/skills/store-wiring.md) — how the fleet provisions skills.
|
||||
- [Skills Ecosystem](/skills/ecosystem.md) — registries and leaderboards.
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills Ecosystem
|
||||
description: "Registries and the leaderboard API for the open agent-skills ecosystem, with a live-verified install snapshot."
|
||||
tags:
|
||||
- skills
|
||||
- skills-sh
|
||||
- ecosystem
|
||||
- registry
|
||||
timestamp: 2026-10-19
|
||||
verified: 2026-10-19
|
||||
---
|
||||
|
||||
# Skills Ecosystem
|
||||
|
||||
The open agent-skills ecosystem is a set of registries over the shared
|
||||
[Agent Skills standard](/skills/agent-skills.md), installed with the
|
||||
[Skills CLI](/skills/skills-cli.md).
|
||||
|
||||
## Registries
|
||||
|
||||
| Registry | Focus |
|
||||
|----------|-------|
|
||||
| [skills.sh](https://skills.sh) | Primary registry and all-time install leaderboard. |
|
||||
| [agentskill.sh](https://agentskill.sh) | Broad directory/marketplace. |
|
||||
| [officialskills.sh](https://officialskills.sh) | Skills from major organizations. |
|
||||
| [qaskills.sh](https://qaskills.sh) | QA and testing skills. |
|
||||
|
||||
## skills.sh leaderboard API
|
||||
|
||||
Fetch the all-time ranking programmatically:
|
||||
|
||||
```bash
|
||||
curl 'https://skills.sh/api/skills/all-time/0'
|
||||
```
|
||||
|
||||
Response is `{ skills, total, hasMore, page }`. Pagination is **zero-based**,
|
||||
**200 skills per page** (`GET /api/skills/all-time/{page}`). Each entry carries
|
||||
`source`, `skillId`, `name`, `installs`, `weeklyInstalls` (last ~8 weeks), and
|
||||
`isOfficial`. Verified live 2026-10-19: page 0 returned 200 entries,
|
||||
`total` 9909, `hasMore` true.
|
||||
|
||||
## Install snapshot (2026-10-19, live)
|
||||
|
||||
Top 10 by all-time installs, queried from the API above:
|
||||
|
||||
| # | Skill | Source | Installs |
|
||||
|---|-------|--------|----------|
|
||||
| 1 | `find-skills` | vercel-labs/skills | 3,927,274 |
|
||||
| 2 | `grill-me` | mattpocock/skills | 1,387,557 |
|
||||
| 3 | `grill-with-docs` | mattpocock/skills | 1,188,473 |
|
||||
| 4 | `agent-browser` | vercel-labs/agent-browser | 1,170,738 |
|
||||
| 5 | `improve-codebase-architecture` | mattpocock/skills | 1,133,991 |
|
||||
| 6 | `tdd` | mattpocock/skills | 1,110,148 |
|
||||
| 7 | `hyperframes-cli` | heygen-com/hyperframes | 1,109,284 |
|
||||
| 8 | `hyperframes` | heygen-com/hyperframes | 1,063,942 |
|
||||
| 9 | `setup-matt-pocock-skills` | mattpocock/skills | 1,024,734 |
|
||||
| 10 | `handoff` | mattpocock/skills | 1,008,869 |
|
||||
|
||||
`mattpocock/skills` dominates the workflow/design middle of the board; a single
|
||||
`find-skills` out-installs the next several combined. Vendor suites (Lark, Azure)
|
||||
that filled ranks 12-50 in the 2026-08-12 snapshot have since dropped out of the
|
||||
head, so this page keeps only a live top-10 rather than a full 50-row table that
|
||||
rots between queries. Re-query the API above for a current census.
|
||||
|
||||
## Repositories
|
||||
|
||||
- [vercel-labs/skills](https://github.com/vercel-labs/skills) — the CLI.
|
||||
- [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) — reference skills.
|
||||
- [anthropics/skills](https://github.com/anthropics/skills) — Anthropic's skill set.
|
||||
- [openai/skills](https://github.com/openai/skills) — OpenAI's skill set.
|
||||
|
||||
## See Also
|
||||
|
||||
- [The Agent Skills Standard](/skills/agent-skills.md)
|
||||
- [Skills CLI](/skills/skills-cli.md)
|
||||
- [Skill Store Wiring](/skills/store-wiring.md)
|
||||
@@ -1,11 +1,14 @@
|
||||
# Skills Documentation
|
||||
|
||||
Distribution and installation patterns for agent skills via npm packages, including SKILL.md structure, discovery rules, and the pi-package system.
|
||||
The open agent-skills ecosystem as the fleet uses it: the standard, the
|
||||
installer CLI, this fleet's provisioning tiers, and the registries.
|
||||
|
||||
## Concept Files
|
||||
|
||||
| File | Type | Description |
|
||||
|------|------|-------------|
|
||||
| [npx-skills.md](npx-skills.md) | reference | Distribution and installation patterns for agent skills via npm packages, including SKILL.md structure and the pi-package system |
|
||||
| [vercel-skills.md](vercel-skills.md) | reference | The meta-installer CLI for cross-agent skill distribution, supporting 68+ agents |
|
||||
* [The Agent Skills Standard](agent-skills.md) — SKILL.md format, frontmatter fields, loading model, authoring practice, skills vs extensions.
|
||||
* [Skills CLI](skills-cli.md) — `npx skills`: commands, sources, scopes, discovery, lock file, agent registry.
|
||||
* [Skill Store Wiring](store-wiring.md) — the three skill tiers on Dank workstations and how omp loads them.
|
||||
* [Skills Ecosystem](ecosystem.md) — registries, the skills.sh leaderboard API, live install snapshot.
|
||||
|
||||
Pi-era skill packaging (`pi install npm:...`, the `pi` package manifest) is
|
||||
archived under [pi](/pi/index.md).
|
||||
|
||||
@@ -1,164 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Npx Skills — Distribution and Installation Patterns
|
||||
description: Distribution and installation patterns for agent skills via npm packages, including SKILL.md structure, discovery rules, and the pi-package system.
|
||||
tags:
|
||||
- skills
|
||||
- npm
|
||||
- agent-skills
|
||||
- distribution
|
||||
- pi-package
|
||||
- unverified
|
||||
timestamp: 2026-08-28
|
||||
---
|
||||
|
||||
# Npx Skills — Distribution and Installation
|
||||
|
||||
In the pi coding agent ecosystem, **"npx skills"** refers to the distribution and installation pattern for agent skills through npm packages. Skills are the content (SKILL.md + scripts); pi packages are the delivery mechanism (npm tarball with a `pi` manifest).
|
||||
|
||||
---
|
||||
|
||||
## The Two-Layer Model
|
||||
|
||||
```
|
||||
npm package (tagged pi-package)
|
||||
├── pi.skills manifest → points to ./skills/
|
||||
└── skills/
|
||||
├── brave-search/SKILL.md
|
||||
├── browser-tools/SKILL.md
|
||||
└── tdd-workflow/SKILL.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Agent Skills Specification
|
||||
|
||||
Pi implements the [Agent Skills standard](https://agentskills.io), which defines:
|
||||
|
||||
- A **frontmatter block** (YAML) at the top of `SKILL.md` with required `name` and `description` fields
|
||||
- A **Markdown body** with the skill's instructions
|
||||
- Optional subdirectories: `scripts/`, `references/`, `assets/`
|
||||
|
||||
The specification is **cross-agent-compatible**: skills written for pi work with Claude Code, Codex CLI, Amp, Droid, and others.
|
||||
|
||||
---
|
||||
|
||||
## How Skills Work in Pi
|
||||
|
||||
1. **At startup**, pi scans all configured skill locations and extracts skill names and descriptions
|
||||
2. **The system prompt** includes available skills in XML format
|
||||
3. **When a task matches**, the agent uses `read` to load the full SKILL.md
|
||||
4. **The agent follows the instructions**, using relative paths to reference scripts and assets
|
||||
|
||||
This is **progressive disclosure**: only descriptions are always in context, full instructions load on-demand.
|
||||
|
||||
---
|
||||
|
||||
## Installing Skills via NPM / Npx
|
||||
|
||||
### Method 1: Direct `pi install` (recommended)
|
||||
|
||||
```bash
|
||||
pi install npm:pi-web-access
|
||||
pi install npm:@anton-kochev/pi-skills
|
||||
pi install npm:bigpowers
|
||||
pi install npm:@monopi/skills
|
||||
```
|
||||
|
||||
### Method 2: Npx-based setup tools
|
||||
|
||||
```bash
|
||||
npx @monopi/monopi # One-command setup
|
||||
npx @monopi/monopi --version 0.2.13 # Pin a version
|
||||
npx @monopi/monopi --local # Project-local install
|
||||
```
|
||||
|
||||
### Method 3: Manual clone (git repos)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pi Packages
|
||||
|
||||
### Package Structure
|
||||
|
||||
```
|
||||
my-pi-package/
|
||||
├── package.json # npm metadata + pi manifest
|
||||
├── skills/ # Conventional directory (auto-discovered)
|
||||
│ ├── my-skill/
|
||||
│ │ └── SKILL.md
|
||||
├── extensions/ # TypeScript extensions
|
||||
├── prompts/ # Prompt templates
|
||||
└── themes/ # TUI themes
|
||||
```
|
||||
|
||||
### package.json with pi Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-pi-package",
|
||||
"keywords": ["pi-package"],
|
||||
"pi": {
|
||||
"extensions": ["./extensions"],
|
||||
"skills": ["./skills"],
|
||||
"prompts": ["./prompts"],
|
||||
"themes": ["./themes"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Package Sources
|
||||
|
||||
| Source Type | Example | Notes |
|
||||
|-------------|---------|-------|
|
||||
| **npm** | `npm:@foo/bar@1.0.0` | Pinned versions, installed to `~/.pi/agent/npm/` |
|
||||
| **git** | `git:github.com/user/repo@v1` | Pinned to tags/commits, cloned to `~/.pi/agent/git/` |
|
||||
| **local** | `./relative/path` | Points to local directory, added without copying |
|
||||
|
||||
---
|
||||
|
||||
## SKILL.md Frontmatter
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | **Yes** | Max 64 chars. Lowercase a-z, 0-9, hyphens only. |
|
||||
| `description` | **Yes** | Max 1024 chars. What the skill does and when to use it. |
|
||||
| `license` | No | License name or reference to bundled file. |
|
||||
| `compatibility` | No | Max 500 chars. Environment requirements. |
|
||||
| `metadata` | No | Arbitrary key-value mapping. |
|
||||
| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
|
||||
| `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. |
|
||||
|
||||
**The description determines when the agent loads the skill. Be specific.**
|
||||
|
||||
---
|
||||
|
||||
## Discovery Rules
|
||||
|
||||
| Location | Scope | Rule |
|
||||
|----------|-------|------|
|
||||
| `~/.pi/agent/skills/` | All projects | Direct root `.md` files + directories with `SKILL.md` |
|
||||
| `.pi/skills/` | Current project | Direct root `.md` files + directories with `SKILL.md` |
|
||||
| `~/.agents/skills/` | All projects | Only directories with `SKILL.md` (root `.md` ignored) |
|
||||
|
||||
---
|
||||
|
||||
## Skills vs Extensions
|
||||
|
||||
| Feature | Skills | Extensions |
|
||||
|---------|--------|------------|
|
||||
| **Format** | Markdown (`SKILL.md`) | TypeScript (`.ts`) |
|
||||
| **Purpose** | Instructions for the LLM | Code that intercepts events |
|
||||
| **Execution** | Agent reads and follows | Runs in pi's Node.js runtime |
|
||||
| **Loading** | On-demand | Always loaded at startup |
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- See [Vercel `skills` CLI](vercel-skills.md) for the meta-installer tool.
|
||||
- The [Agent Skills specification](https://agentskills.io/specification) is the canonical format.
|
||||
@@ -0,0 +1,127 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI
|
||||
description: "The Vercel Labs `skills` CLI: commands, sources, install scopes, discovery rules, lock file, environment variables, and the agent registry."
|
||||
tags:
|
||||
- skills
|
||||
- cli
|
||||
- vercel
|
||||
- meta-installer
|
||||
resource: https://github.com/vercel-labs/skills
|
||||
timestamp: 2026-10-19
|
||||
verified: 2026-10-19
|
||||
---
|
||||
|
||||
# Skills CLI
|
||||
|
||||
`npx skills` is the CLI for the open agent-skills ecosystem
|
||||
([vercel-labs/skills](https://github.com/vercel-labs/skills)). It is a
|
||||
meta-installer: it pulls `SKILL.md` bundles from a source and links or copies
|
||||
them into each supported agent's skill directory. No global install; run via
|
||||
`npx`. Version 1.7.2 (`package.json`, 2026-10-19).
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Aliases | Purpose |
|
||||
|---------|---------|---------|
|
||||
| `skills add <source>` | `a` | Install skills from a source. |
|
||||
| `skills use <source>[@skill]` | | Emit a prompt for one skill (pipe to an agent) or launch an agent with `--agent`, without installing. |
|
||||
| `skills list` | `ls` | List installed skills (`-g` global only, `-a <agent>` filter). |
|
||||
| `skills find [query]` | | Interactive (fzf-style) or keyword search; `--owner <org>` scans an org. |
|
||||
| `skills update [skills...]` | | Update installed skills to latest; `-g`/`-p` scope, `-y` auto-scope. |
|
||||
| `skills remove [skills]` | `rm`, `r` | Remove installed skills from agents. |
|
||||
| `skills init [name]` | | Create a `SKILL.md` template. |
|
||||
| `skills experimental_install` | `i`, `install` | Restore installs recorded in the lock file. |
|
||||
| `skills experimental_sync` | | Sync installed skills against sources. |
|
||||
| `skills check` | | Report drift: GitHub tree SHA vs locked `skillFolderHash`. |
|
||||
|
||||
`skills check` and `skills update` share a dispatch path in `src/cli.ts`
|
||||
(2026-10-19). For `check`/`update`, only GitHub-backed skills carrying both
|
||||
`skillFolderHash` and `skillPath` are compared.
|
||||
|
||||
### `add` options
|
||||
|
||||
| Option | Effect |
|
||||
|--------|--------|
|
||||
| `-g, --global` | User directory instead of project. |
|
||||
| `-a, --agent <agents...>` | Target specific agents (`'*'` for all). |
|
||||
| `-s, --skill <skills...>` | Specific skills by name (`'*'` for all). |
|
||||
| `-l, --list` | List the source's skills without installing. |
|
||||
| `--copy` | Copy instead of symlink. |
|
||||
| `-y, --yes` | Skip prompts (CI-friendly). |
|
||||
| `--all` | All skills to all agents, no prompts. |
|
||||
| `--full-depth` | Discover `SKILL.md` outside standard container dirs too. |
|
||||
|
||||
## Sources
|
||||
|
||||
GitHub shorthand (`owner/repo`), full GitHub URL, a tree path to one skill
|
||||
(`.../tree/main/skills/<name>`), GitLab URL, Azure DevOps URL, any git URL, a
|
||||
local path, or a direct download URL (single `SKILL.md`, or `.zip`/`.tar`/
|
||||
`.tar.gz`/`.tgz`). Private repos reuse the credentials git already has;
|
||||
`GITHUB_TOKEN`/`GH_TOKEN` override for API access. Direct downloads cap at
|
||||
10 MiB compressed, 25 MiB extracted, 1000 files (override with
|
||||
`SKILLS_DOWNLOAD_MAX_BYTES`, `SKILLS_EXTRACT_MAX_BYTES`,
|
||||
`SKILLS_EXTRACT_MAX_FILES`).
|
||||
|
||||
## Install scope and method
|
||||
|
||||
| Scope | Flag | Location |
|
||||
|-------|------|----------|
|
||||
| Project | default | `./<agent>/skills/` |
|
||||
| Global | `-g` | `~/<agent>/skills/` |
|
||||
|
||||
Symlink (recommended: one canonical copy, easy update) or `--copy` (independent
|
||||
copies, for hosts where symlinks are unsupported).
|
||||
|
||||
## Skill discovery in a source repo
|
||||
|
||||
The CLI walks each container directory up to three levels: flat
|
||||
(`skills/<name>/SKILL.md`) and one- or two-level catalog layouts. Containers:
|
||||
repo root, `skills/` (and `.curated`/`.experimental`/`.system`), plus
|
||||
per-agent dirs (`.claude/skills/`, `.agents/skills/`, `.pi/skills/`, and
|
||||
dozens more). A `SKILL.md` at a shallower level shadows deeper ones.
|
||||
`--full-depth` also scans outside containers (`examples/`, `tests/`). If a
|
||||
`.claude-plugin/marketplace.json` or `plugin.json` exists, its declared skill
|
||||
paths load too (Claude Code marketplace compatibility). Nothing found in
|
||||
containers triggers a recursive search.
|
||||
|
||||
## Lock file
|
||||
|
||||
| Type | Path |
|
||||
|------|------|
|
||||
| Global | `$XDG_STATE_HOME/skills/.skill-lock.json`, else `~/.agents/.skill-lock.json` |
|
||||
| Project | `skills-lock.json` (commit it) |
|
||||
|
||||
Schema **v3**; key field `skillFolderHash` (GitHub tree SHA per skill folder).
|
||||
A lock file older than v3 is wiped, not migrated — reinstall to repopulate
|
||||
(`src/skill-lock.ts`, 2026-10-19).
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variable | Effect |
|
||||
|----------|--------|
|
||||
| `INSTALL_INTERNAL_SKILLS` | `1`/`true` reveals `metadata.internal: true` skills. |
|
||||
| `DISABLE_TELEMETRY` | Disable anonymous usage telemetry. |
|
||||
| `DO_NOT_TRACK` | Alternative telemetry opt-out. |
|
||||
| `GITHUB_TOKEN`, `GH_TOKEN` | Explicit GitHub API token. |
|
||||
|
||||
## Agent registry
|
||||
|
||||
79 agents supported (upstream README + `--agent` registry, checked 2026-10-19);
|
||||
the CLI auto-detects installed agents, prompting when it finds none. Each agent
|
||||
maps to a project and global path (e.g. `claude-code` → `.claude/skills/` /
|
||||
`~/.claude/skills/`; `pi` → `.pi/skills/` / `~/.pi/agent/skills/`). The
|
||||
authoritative table lives in the upstream README; this bundle does not mirror
|
||||
it because the list churns. omp is not a registered agent — see
|
||||
[Skill Store Wiring](/skills/store-wiring.md).
|
||||
|
||||
## Citations
|
||||
|
||||
- [vercel-labs/skills README](https://github.com/vercel-labs/skills) — 2026-10-19.
|
||||
- `src/cli.ts`, `src/skill-lock.ts`, `package.json` at `vercel-labs/skills@main` — 2026-10-19.
|
||||
|
||||
## See Also
|
||||
|
||||
- [The Agent Skills Standard](/skills/agent-skills.md)
|
||||
- [Skill Store Wiring](/skills/store-wiring.md)
|
||||
- [Skills Ecosystem](/skills/ecosystem.md)
|
||||
+2
-3
@@ -23,7 +23,7 @@ Three tiers, one owner each:
|
||||
## How omp loads them
|
||||
|
||||
omp is NOT a registered agent in the `skills` CLI (79-agent registry checked
|
||||
2026-10-18; see [Agent Support](/tools/vercel-labs-skills/agent-support.md)) —
|
||||
2026-10-18; see [Skills CLI](/skills/skills-cli.md)) —
|
||||
`skills add` never writes anywhere under `~/.omp`. Instead omp's own `agents`
|
||||
provider reads the store **directly**: `skills.enableAgentsUser` (default true)
|
||||
loads `~/.agents/skills/*/SKILL.md`. No per-skill symlinks in the repo — the
|
||||
@@ -59,5 +59,4 @@ all of the above; authored skills always win name collisions against it.
|
||||
|
||||
## Related
|
||||
|
||||
* [Lock File](/tools/vercel-labs-skills/lock-file.md) — hash-based update checking
|
||||
* [Agent Support](/tools/vercel-labs-skills/agent-support.md) — full CLI agent registry
|
||||
* [Skills CLI](/skills/skills-cli.md) — lock file, update checking, and the full agent registry
|
||||
@@ -1,166 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Vercel Labs `skills` CLI
|
||||
description: The meta-installer CLI for cross-agent skill distribution, supporting 68+ agents with add/use/find/list/update/remove commands.
|
||||
tags:
|
||||
- skills
|
||||
- vercel
|
||||
- meta-installer
|
||||
- cross-agent
|
||||
- cli
|
||||
- unverified
|
||||
timestamp: 2026-08-28
|
||||
---
|
||||
|
||||
# Vercel Labs `skills` CLI
|
||||
|
||||
`skills` is the CLI for the open agent skills ecosystem, created by Gunnar (@rauchg) at Vercel. It is a **meta-installer** that downloads skills from repositories and installs them into 68+ supported coding agents' skill directories.
|
||||
|
||||
**Repository:** [vercel-labs/skills](https://github.com/vercel-labs/skills)
|
||||
**Specification:** [Agent Skills](https://agentskills.io)
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
No global installation needed — run directly via `npx`:
|
||||
|
||||
```bash
|
||||
npx skills add vercel-labs/agent-skills # Install from GitHub
|
||||
npx skills add vercel-labs/agent-skills --list # List without installing
|
||||
npx skills use vercel-labs/agent-skills@skill-name # Use without installing
|
||||
npx skills find typescript # Search
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
### `skills add` — Install Skills
|
||||
|
||||
```bash
|
||||
npx skills add <source> [options]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `-g, --global` | Install to user directory (`~/`) |
|
||||
| `-a, --agent <agents...>` | Target specific agents |
|
||||
| `-s, --skill <skills...>` | Install specific skills (use `'*'` for all) |
|
||||
| `-l, --list` | List available skills |
|
||||
| `--copy` | Copy files instead of symlinking |
|
||||
| `-y, --yes` | Skip confirmation prompts |
|
||||
| `--all` | Install all to all agents |
|
||||
|
||||
### `skills use` — Use Without Installing
|
||||
|
||||
```bash
|
||||
npx skills use <source> [options]
|
||||
# Generates prompt to stdout, or launches agent with --agent
|
||||
```
|
||||
|
||||
### `skills list` (alias: `ls`)
|
||||
|
||||
```bash
|
||||
npx skills list # All installed skills
|
||||
npx skills ls -g # Global only
|
||||
```
|
||||
|
||||
### `skills find` — Search
|
||||
|
||||
```bash
|
||||
npx skills find # Interactive search
|
||||
npx skills find typescript # By keyword
|
||||
```
|
||||
|
||||
### `skills update`
|
||||
|
||||
```bash
|
||||
npx skills update # Update all (interactive)
|
||||
npx skills update -g # Global only
|
||||
npx skills update -y # Auto-detect scope
|
||||
```
|
||||
|
||||
### `skills remove` (alias: `rm`)
|
||||
|
||||
```bash
|
||||
npx skills remove # Interactive
|
||||
npx skills remove my-skill -a claude-code -g
|
||||
npx skills remove --all # Remove everything
|
||||
```
|
||||
|
||||
### `skills init` — Create Template
|
||||
|
||||
```bash
|
||||
npx skills init # Current directory
|
||||
npx skills init my-skill # Subdirectory
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Source Formats
|
||||
|
||||
```bash
|
||||
npx skills add owner/repo # GitHub shorthand
|
||||
npx skills add https://github.com/owner/repo # Full URL
|
||||
npx skills add https://gitlab.com/org/repo # GitLab
|
||||
npx skills add git@github.com:owner/repo.git # Git URL
|
||||
npx skills add ./my-local-skills # Local path
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation Scope
|
||||
|
||||
| Scope | Flag | Location | Use Case |
|
||||
|-------|------|----------|----------|
|
||||
| **Project** | _(default)_ | `./<agent>/skills/` | Committed with project |
|
||||
| **Global** | `-g` | `~/<agent>/skills/` | All projects |
|
||||
|
||||
Symlink (recommended) or copy mode.
|
||||
|
||||
---
|
||||
|
||||
## Agent Support
|
||||
|
||||
The CLI supports **68+ agents**. Key ones:
|
||||
|
||||
| Agent | `--agent` | Project Path | Global Path |
|
||||
|-------|-----------|--------------|-------------|
|
||||
| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
|
||||
| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
|
||||
| Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
|
||||
| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
|
||||
| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
|
||||
| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
|
||||
| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
|
||||
|
||||
Full table available in the [source repository](https://github.com/vercel-labs/skills).
|
||||
|
||||
---
|
||||
|
||||
## Lock File System
|
||||
|
||||
| Type | Path | Scope |
|
||||
|------|------|-------|
|
||||
| **Global lock** | `~/.agents/.skill-lock.json` | User-wide |
|
||||
| **Local lock** | `skills-lock.json` | Project (check in) |
|
||||
|
||||
`skills check` compares GitHub tree SHA with the lock file. `skills update` reinstalls changed skills.
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `INSTALL_INTERNAL_SKILLS` | Set to `1` to show skills marked `internal: true` |
|
||||
| `DISABLE_TELEMETRY` | Disable anonymous usage telemetry |
|
||||
| `DO_NOT_TRACK` | Alternative way to disable telemetry |
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- See [Npx Skills](npx-skills.md) for the pi-specific npm package distribution system.
|
||||
- The [Agent Skills specification](https://agentskills.io/specification) is the shared standard.
|
||||
@@ -11,15 +11,29 @@ tags:
|
||||
generated:
|
||||
by: chief-designer/agent
|
||||
at: 2026-08-26T00:00:00Z
|
||||
verified: 2026-10-18
|
||||
verified: 2026-10-19
|
||||
---
|
||||
|
||||
# Dankclaw
|
||||
|
||||
Strix Halo mini-PC carrying the fleet's secondary models and most of the
|
||||
service stack (Gitea, Caddy, OpenWebUI, SearXNG). Two GPU-class devices: the
|
||||
Radeon 8060S iGPU with 119 GiB unified memory, and the RTX 3090 moved over
|
||||
from Dankserver in September 2026.
|
||||
Strix Halo mini-PC carrying the fleet's secondary models and the bulk of the
|
||||
service stack. Two GPU-class devices: the Radeon 8060S iGPU with 119 GiB
|
||||
unified memory, and the RTX 3090 moved over from Dankserver in September 2026.
|
||||
|
||||
## Service Stack (live census, 32 containers, 2026-10-19)
|
||||
|
||||
User-scope Podman Quadlet units (`~/.config/containers/systemd/`) unless
|
||||
noted. Full names; detail pages where they exist.
|
||||
|
||||
| Group | Containers |
|
||||
|-------|-----------|
|
||||
| Inference (root systemd, not quadlet) | `frank-dragoon` (:7770), `frank-zealot` (:7771) |
|
||||
| TTS | `frank-tts` (:7772), `frank-tts-engine` (:8880) |
|
||||
| Git forge | `gitea-server` (:3000/:2222), `gitea-postgres` — see [/tools/gitea/](/tools/gitea/index.md) |
|
||||
| Web/search | `caddy` (:80/:443, Porkbun build), `searxng` (:8081/:8082 via `gluetun`), `searxng-valkey`, `marreta`, `marreta_browser`, `anubis` (bot shield), `chrome-devtools-protocol` (headless-shell) |
|
||||
| Identity | `authentik-server` (:9000), `authentik-worker`, `authentik-outpost`, `authentik-outpost-ldap` (:389/:636), `authentik-postgres` |
|
||||
| Monitoring | `prometheus` (:9090), `grafana` (:3002), `loki`, `alloy`, `alertmanager` (:9093), `node-exporter` — loopback-only ports |
|
||||
| Media/apps | `open-webui` (:3005), `comfyui` (:8188, ROCm `gfx1151`), `seerr` (:5055), `hermes`/`hermes-webui`/`hermes-dashboard` (:9119), `ntfy` (pubsub), `pihole` (:53 DNS, :8083 admin) |
|
||||
|
||||
## Connection Details
|
||||
|
||||
@@ -33,8 +47,8 @@ from Dankserver in September 2026.
|
||||
|
||||
| Model ID | Unit | Endpoint | Engine / weights |
|
||||
|----------|------|----------|------------------|
|
||||
| `frank-dragoon` | `frank-dragoon.service` (root) | `:7770` | halogen-flash-server container — Quat3rnion NATIVE v2 abliterated Qwen3.8-Flash-Next, MTP spec decode, 2 slots over ONE 200,704-position pool, vision ON, **Strix Halo iGPU** (unified memory) |
|
||||
| `frank-zealot` | `frank-zealot.service` (root) | `:7771` | llama.cpp (PrismML fork, build 10754) — Ternary-Bonsai-2-27B PQ2_0 GGUF (qwen35 hybrid), 2×200,704 slots, q8_0 K+V, mmproj vision, **RTX 3090** |
|
||||
| `frank-dragoon` | `frank-dragoon.service` (root) | `:7770` (container `frank-dragoon-halogen`, 7770→8731) | halogen-flash-server container (`ghcr.io/peonist-ai/halogen-flash-server`, digest-pinned) — Quat3rnion NATIVE v2 abliterated Qwen3.8-Flash-Next, MTP spec decode, 2 slots over ONE **401,408**-position pool at ctx **200,704**, vision ON, **Strix Halo iGPU** (unified memory) |
|
||||
| `frank-zealot` | `frank-zealot.service` (root) | `:7771` | llama.cpp (PrismML fork, build 10777) — Ternary-Bonsai-**2-9B** PQ2_0-MTP GGUF (qwen35 hybrid), 2×262,144 slots over one 524,288 pool, **unquantized f16 K+V**, MTP off, mmproj Q8_0 vision, **RTX 3090** |
|
||||
|
||||
Harness-side context windows (`agent/models.yml`): dragoon 155,648,
|
||||
zealot 200,704 per slot. The models.yml display labels "(dankclaw-gpu)" /
|
||||
|
||||
@@ -86,4 +86,4 @@ The old page (verified 2026-08-28) listed an RTX 3090, 60 GiB RAM, and a
|
||||
|
||||
- [[dankclaw|dankclaw]] — the other inference box (dragoon + zealot)
|
||||
- [[network|network]] — Network topology
|
||||
- [/pi/statusline.md](/pi/statusline.md) — where these models surface in the TUI
|
||||
- [/core/statusline.md](/core/statusline.md) — where these models surface in the TUI
|
||||
|
||||
@@ -9,6 +9,7 @@ tags:
|
||||
- kernel
|
||||
- performance
|
||||
timestamp: 2026-08-06
|
||||
verified: 2026-10-19
|
||||
---
|
||||
|
||||
# CachyOS
|
||||
@@ -22,8 +23,8 @@ CachyOS is an Arch Linux-based rolling release distribution focused on performan
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **OS** | CachyOS (rolling) |
|
||||
| **Kernel** | `linux-cachyos 7.1.4-1` |
|
||||
| **LTS Kernel** | `linux-cachyos-lts 6.18.38-2` |
|
||||
| **Kernel** | `linux-cachyos` (performance series — 7.2.9-2 at 2026-10-19 probe) |
|
||||
| **LTS Kernel** | `linux-cachyos-lts` (6.18.55-2 at 2026-10-19 probe) |
|
||||
| **Package Manager** | pacman |
|
||||
| **Init** | systemd |
|
||||
| **Display Manager** | SDDM |
|
||||
@@ -55,8 +56,8 @@ CachyOS uses v3 repositories alongside standard Arch repos:
|
||||
|
||||
| Package | Description |
|
||||
|---------|-------------|
|
||||
| `cachyos-kernel-manager` | Simple kernel manager (1.19.0) |
|
||||
| `cachyos-hello` | Welcome screen (0.26.0) |
|
||||
| `cachyos-kernel-manager` | Simple kernel manager |
|
||||
| `cachyos-hello` | Welcome screen |
|
||||
| `cachyos-gaming-meta` | Gaming dependencies meta-package |
|
||||
| `cachyos-gaming-applications` | Common gaming applications |
|
||||
| `cachyos-ananicy-rules` | Process auto-categorization rules |
|
||||
|
||||
@@ -4,7 +4,7 @@ Private Git hosting on dankclaw. Two quadlet-managed containers in the rootless
|
||||
|
||||
**Host:** dankclaw (192.168.0.143 LAN)
|
||||
**Config:** `~/.config/containers/systemd/gitea-{postgres,server}.container` + `gitea.network`
|
||||
**Local access:** `http://dankclaw:3000` (verified 2026-10-18)
|
||||
**Local access:** `http://dankclaw:3000` — Gitea 1.27.3 (`/api/v1/version`, probed 2026-10-19)
|
||||
**Domain:** `https://gitea.franksdank.cloud` (live; served by fleet Caddy, DNS-01 TLS)
|
||||
|
||||
## Architecture
|
||||
@@ -53,16 +53,7 @@ The quadlet files and `.env` templates are tracked in the `serverAppConfigs` dep
|
||||
|
||||
## See Also
|
||||
|
||||
- [[architecture|architecture]] — network topology and ports
|
||||
- [[management|management]] — operations, upgrades, backups, incident log
|
||||
- [[client-access|client-access]] — client-side tokens, the credential store, and the git 2.56 store-format trap
|
||||
- [[data-persistence|data-persistence]] — volumes and backup strategy
|
||||
- [[containers|containers]] — quadlet reference
|
||||
|
||||
* [Gitea Architecture](architecture.md) — Gitea container architecture, network topology, and Caddy reverse proxy configuration on dankclaw.
|
||||
|
||||
* [Gitea Data Persistence](data-persistence.md) — Gitea data persistence, volume mounts, ownership, and backup strategy on dankclaw.
|
||||
|
||||
* [Gitea Management](management.md) — Gitea container management, boot persistence, troubleshooting, upgrades, and backup procedures on dankclaw.
|
||||
|
||||
* [Gitea Client Access](client-access.md) — Token-based HTTP access from client workstations, credential store layout, and verification.
|
||||
* [Gitea Architecture](architecture.md) — container architecture, network topology, ports.
|
||||
* [Gitea Data Persistence](data-persistence.md) — data layout, ownership mapping, backup strategy.
|
||||
* [Gitea Management](management.md) — operations, upgrades, backups, incident log.
|
||||
* [Gitea Client Access](client-access.md) — token-based HTTP access from clients, credential store, git 2.56 store-format trap.
|
||||
|
||||
@@ -229,5 +229,5 @@ See [[noctalia-shell]] for IPC integration patterns.
|
||||
## See Also
|
||||
|
||||
- [[noctalia-shell|noctalia-shell.md]] — Desktop environment integration
|
||||
- [[niri|niri/index.md]] — Compositor configuration
|
||||
- [niri](niri/index.md) — Compositor configuration
|
||||
- [`handy --help`](https://github.com/cjpais/Handy) — CLI reference
|
||||
|
||||
+10
-24
@@ -6,21 +6,18 @@ Configuration guides and reference material for installed software. Each tool ha
|
||||
|
||||
## Available Tools
|
||||
|
||||
* [[cachyos|cachyos]] — Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on the workstation.
|
||||
* [applications](applications.md) — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming.
|
||||
* [cachyos](cachyos.md) — Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on the workstation.
|
||||
* [comfyui](comfyui/index.md) — Node-based AI image generation engine on dankclaw. FLUX.2 klein 4B, CPU backend, systemd managed.
|
||||
* [live-sync](live-sync.md) — Heartbeat daemon committing machine-written paths (memories, managed-skills, live config, dotfiles) in the command-center checkout; systemd user timer, alerts via ntfy.
|
||||
* [[applications|applications]] — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming.
|
||||
* ](ghostty/index.md) — GPU-accelerated terminal emulator with extensive configuration, keybindings, and shaders.
|
||||
* ](gitea/index.md) — Private Git hosting on dankclaw. Quadlet-managed containers: Gitea, PostgreSQL, Caddy.
|
||||
* ](llama-cpp/index.md) — Local LLM inference server supporting GGUF models with OpenAI-compatible API.
|
||||
* [[linux-power-management|linux-power-management]] — Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems.
|
||||
* [[noctalia-shell|noctalia-shell]] — Native desktop environment for Niri — launcher, control center, settings, lock screen, session menu, hotkey overlay, media controls, and system management.
|
||||
* [ghostty](ghostty/index.md) — GPU-accelerated terminal emulator with extensive configuration, keybindings, and shaders.
|
||||
* [gitea](gitea/index.md) — Private Git hosting on dankclaw. Quadlet-managed containers: Gitea, PostgreSQL, Caddy.
|
||||
* [handy](handy.md) — Offline speech-to-text transcription with WebKitGTK backend and Tauri v2 UI.
|
||||
* [live-sync](live-sync.md) — Heartbeat daemon committing machine-written paths (memories, managed-skills, live config, dotfiles) in the command-center checkout; systemd user timer, alerts via ntfy.
|
||||
* [llama.cpp](llama-cpp/index.md) — Local LLM inference server supporting GGUF models with OpenAI-compatible API.
|
||||
* [linux-power-management](linux-power-management.md) — Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems.
|
||||
* [niri](niri/index.md) — Scrollable-tiling Wayland compositor — configuration, keybindings, and architecture for the workstation.
|
||||
* [npx Skills](npx-skills/index.md) — Distribution and installation tips for pi skill packages on npm, ecosystem overview, and skill specification.
|
||||
* [ornith-llama-cpp-setup](ornith-llama-cpp-setup/index.md) — Setup and reference for running Ornith MoE models with llama.cpp server for local inference.
|
||||
* [[tmux|tmux]] — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.
|
||||
* ](vercel-labs-skills/index.md) — Complete list of 68+ supported coding agents, their --agent flags, installation paths, and the SKILL.md specification.
|
||||
* [noctalia-shell](noctalia-shell.md) — Native desktop environment for Niri — launcher, control center, settings, lock screen, session menu, hotkey overlay, media controls, and system management.
|
||||
* [tmux](tmux.md) — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.
|
||||
|
||||
## Adding a New Tool
|
||||
|
||||
@@ -28,16 +25,5 @@ Configuration guides and reference material for installed software. Each tool ha
|
||||
2. Add `index.md` as the entry point (no frontmatter for directory listings)
|
||||
3. Create concept files with frontmatter if content exceeds one file
|
||||
4. Update this index
|
||||
5. Log the change in `log.md`
|
||||
|
||||
* [Default Applications](applications.md) — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming.
|
||||
|
||||
* [CachyOS](cachyos.md) — Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on the workstation.
|
||||
|
||||
* [Linux Power Management](linux-power-management.md) — Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems.
|
||||
|
||||
* [Noctalia Shell](noctalia-shell.md) — Native desktop environment for Niri — launcher, control center, settings, lock screen, session menu, hotkey overlay, media controls, and system management.
|
||||
|
||||
* [Handy](handy.md) — Offline speech-to-text transcription with WebKitGTK backend and Tauri v2 UI.
|
||||
|
||||
* [tmux](tmux.md) — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.
|
||||
Skills tooling lives in [/skills/](../skills/index.md), not in this directory.
|
||||
|
||||
@@ -9,7 +9,7 @@ tags:
|
||||
timestamp: 2026-08-06
|
||||
---
|
||||
|
||||
Comprehensive guide to sleep/wake configuration and diagnostics on Linux systems. Covers systemd sleep, kernel states, NVIDIA GPU power management, and diagnostic tools.
|
||||
General sleep/wake configuration and diagnostics for Linux systems: systemd sleep, kernel states, NVIDIA GPU power management, wake sources, and diagnostic tools. Fleet scope: the dev workstation `blankpad` is an AMD Cezanne APU exposing **s2idle only** (`/sys/power/mem_sleep` shows no `deep`); the NVIDIA section applied to the retired **dankware** Alienware m16 R2 (see [Sleep/Wake Research](../research/index.md)) and to any future NVIDIA box.
|
||||
|
||||
---
|
||||
|
||||
@@ -294,8 +294,3 @@ dmesg | tail -30
|
||||
journalctl -b -0 | grep -iE 'error|fail|nvidia' | tail -20
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- The [AGENTS.md Format](../core/agents-md-format.md) defines the system-level instruction contract that governs how agent sessions configure these systems.
|
||||
|
||||
@@ -152,4 +152,3 @@ LLAMA_ARG_MODEL=/models/model.gguf LLAMA_ARG_CTX_SIZE=8192 llama-server
|
||||
## Cross-References
|
||||
|
||||
- See [Setup Guide](setup.md) for build instructions, GPU offloading, and deployment.
|
||||
- See [Ornith Setup](../ornith-llama-cpp-setup/index.md) for running Ornith models.
|
||||
|
||||
@@ -263,4 +263,3 @@ sudo systemctl start llama-server
|
||||
## Cross-References
|
||||
|
||||
- See [Overview](index.md) for API reference and usage examples.
|
||||
- See [Ornith Setup](../ornith-llama-cpp-setup/index.md) for model-specific configuration.
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
---
|
||||
type: reference
|
||||
title: Niri Keybindings
|
||||
description: Live keybinding cheat sheet generated from keybinds.kdl — do not edit by hand.
|
||||
tags:
|
||||
- niri
|
||||
- keybindings
|
||||
generated: { by: scripts/gen-keybinds.sh }
|
||||
---
|
||||
|
||||
# Niri Keybindings
|
||||
|
||||
> GENERATED by `scripts/gen-keybinds.sh` from `keybinds.kdl` — do not edit by hand.
|
||||
@@ -64,10 +74,10 @@
|
||||
| `Mod+K` | focus-window-up |
|
||||
| `Mod+Down` | focus-window-down |
|
||||
| `Mod+J` | focus-window-down |
|
||||
| `Mod+CTRL+Left` | swap-window-left |
|
||||
| `Mod+CTRL+H` | swap-window-left |
|
||||
| `Mod+CTRL+Right` | swap-window-right |
|
||||
| `Mod+CTRL+L` | swap-window-right |
|
||||
| `Mod+CTRL+Left` | consume-or-expel-window-left |
|
||||
| `Mod+CTRL+H` | consume-or-expel-window-left |
|
||||
| `Mod+CTRL+Right` | consume-or-expel-window-right |
|
||||
| `Mod+CTRL+L` | consume-or-expel-window-right |
|
||||
| `Mod+CTRL+Alt+Left` | move-column-left |
|
||||
| `Mod+CTRL+Alt+H` | move-column-left |
|
||||
| `Mod+CTRL+Alt+Right` | move-column-right |
|
||||
@@ -141,10 +151,10 @@
|
||||
| `Mod+CTRL+F` | expand-column-to-available-width |
|
||||
| `Mod+C` | center-column |
|
||||
| `Mod+CTRL+C` | center-visible-columns |
|
||||
| `Mod+Minus` | set-column-width "-10%" |
|
||||
| `Mod+Equal` | set-column-width "+10%" |
|
||||
| `Mod+Shift+Minus` | set-window-height "-10%" |
|
||||
| `Mod+Shift+Equal` | set-window-height "+10%" |
|
||||
| `Mod+Minus` | set-column-width "-5%" |
|
||||
| `Mod+Equal` | set-column-width "+5%" |
|
||||
| `Mod+Shift+Minus` | set-window-height "-5%" |
|
||||
| `Mod+Shift+Equal` | set-window-height "+5%" |
|
||||
|
||||
## Modes
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
type: reference
|
||||
title: Screenshot Matrix
|
||||
description: Screenshot setup on blankpad — flameshot retired (all modes hang via portal on 2+ outputs, niri#4313); niri-native binds: all-monitors script, focused-screen capture, interactive UI. Includes the niri spawn-sh PATH trap.
|
||||
description: "Screenshot setup on blankpad — flameshot retired (all modes hang via portal on 2+ outputs, niri#4313); niri-native binds: all-monitors script, focused-screen capture, interactive UI. Includes the niri spawn-sh PATH trap."
|
||||
tags:
|
||||
- niri
|
||||
- flameshot
|
||||
|
||||
@@ -429,7 +429,7 @@ noctalia msg templates-apply
|
||||
|
||||
## See Also
|
||||
|
||||
- [[niri|niri/index.md]] — Compositor configuration
|
||||
- [niri](niri/index.md) — Compositor configuration
|
||||
- [[displays|displays]] — Display layout
|
||||
- [[cachyos|cachyos]] — Operating system documentation
|
||||
- [`noctalia msg --help`](https://github.com/Noctalia/noctalia) — Full command reference
|
||||
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
type: guide
|
||||
title: Skill Author Best Practices
|
||||
description: Tips for writing good skill descriptions, organizing files, and distributing pi packages on npm.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- best-practices
|
||||
- authoring
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Best Practices for Skill Authors
|
||||
|
||||
## Description Writing
|
||||
|
||||
1. **Be specific about capabilities** — "Extracts text and tables from PDF files, fills forms, merges documents" vs "Helps with documents"
|
||||
2. **Include trigger phrases** — "Use when working with PDF files or when user mentions PDFs, forms, or document extraction"
|
||||
3. **Keep under 1024 characters**
|
||||
4. **Write in third person**
|
||||
5. **First sentence = what it does, second sentence = when to use it**
|
||||
|
||||
## File Organization
|
||||
|
||||
1. **Use progressive disclosure** — Keep SKILL.md focused; reference detailed docs in `references/`
|
||||
2. **Add scripts for deterministic operations** — When the same code would be generated repeatedly, scripts save tokens and improve reliability
|
||||
3. **Split files when content exceeds ~500 lines** — Agents load the entire file on activation
|
||||
4. **Include a config.json** for configurable paths or settings
|
||||
5. **Add tests** — Include test scripts and mock data for validation
|
||||
|
||||
## Security
|
||||
|
||||
1. **Review skill content before use** — Skills can instruct the model to perform any action
|
||||
2. **Scripts run with your full system permissions** — Only install from trusted sources
|
||||
3. **Document dependencies clearly** — List all required tools, API keys, and setup steps
|
||||
|
||||
## Distribution
|
||||
|
||||
1. **Add `pi-package` keyword** to package.json for npm discoverability
|
||||
2. **Include `video` or `image` fields** in the pi manifest for the gallery
|
||||
3. **Use peerDependencies** for pi-provided packages: `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, `typebox`
|
||||
4. **List runtime deps in `dependencies`** — They get installed automatically
|
||||
|
||||
## Related
|
||||
|
||||
* [Package Structure](/tools/npx-skills/package-structure.md) — How to structure your npm package
|
||||
* [Installation](/tools/npx-skills/installation.md) — How users will install your skills
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Ecosystem Resources
|
||||
description: GitHub repositories, npm packages, and community resources for the pi skills ecosystem.
|
||||
tags:
|
||||
- unverified
|
||||
- ecosystem
|
||||
- npm
|
||||
- repositories
|
||||
- community
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Ecosystem Resources
|
||||
|
||||
## Official Documentation
|
||||
|
||||
- [Pi Skills Documentation](https://github.com/earendil-works/pi)
|
||||
- [Pi Packages Documentation](https://github.com/earendil-works/pi)
|
||||
- [Agent Skills Specification](https://agentskills.io/specification)
|
||||
- [Agent Skills Integration Guide](https://agentskills.io/integrate-skills)
|
||||
- [Pi Packages Gallery](https://pi.dev/packages)
|
||||
|
||||
## GitHub Repositories
|
||||
|
||||
| Repository | Description | Stars |
|
||||
|------------|-------------|-------|
|
||||
| [badlogic/pi-skills](https://github.com/badlogic/pi-skills) | Official skills collection (brave-search, browser-tools, Google APIs, transcription) | 2,138 |
|
||||
| [ifiokjr/monopi](https://github.com/ifiokjr/monopi) | One-click pi setup with skills, extensions, themes, subagents | 136 |
|
||||
| [VenTheZone/pi-dots](https://github.com/VenTheZone/pi-dots) | 60+ skills covering research, content, project management, debugging | 42 |
|
||||
| [HazAT/pi-config](https://github.com/HazAT/pi-config) | Personal pi config with skills, extensions, agents | 418 |
|
||||
| [qualisero/awesome-pi-agent](https://github.com/qualisero/awesome-pi-agent) | Awesome list of pi add-ons, hooks, tools, skills | 1,093 |
|
||||
| [getpipher/pi-package-index](https://github.com/getpipher/pi-package-index) | Unofficial community index with GitHub stars + downloads | 2 |
|
||||
| [lukaspanni/pi-package-template](https://github.com/lukaspanni/pi-package-template) | Template for creating pi packages | 0 |
|
||||
|
||||
## Notable npm Packages
|
||||
|
||||
| Package | Description | Keywords |
|
||||
|---------|-------------|----------|
|
||||
| `pi-web-access` | Web search, URL fetching, PDF extraction, YouTube analysis | pi-package, web-search, perplexity |
|
||||
| `@wierdbytes/pi-peon` | Sound-pack player for pi (installed) | pi-package, peon, sound |
|
||||
| `bigpowers` | 73 agent skills for solo developers | skills, agents, claude, pi-package |
|
||||
| `pi-spark` | Polishes daily pi experience | pi-coding-agent, pi-package |
|
||||
| `@anton-kochev/pi-skills` | Planning, TDD, SRS, requirements skills | pi-package, pi-skill, tdd |
|
||||
| `@monopi/skills` | Curated skill packs (debug-helper, btw, nushell) | pi-package, skills |
|
||||
| `@dietrichgebert/ponytail` | Lazy senior dev mode with skills | opencode, pi-package, skills |
|
||||
| `pi-mcp-adapter` | MCP adapter for pi | pi-package, mcp |
|
||||
| `pi-subagents` | Subagent delegation with chains | pi-package, subagents |
|
||||
| `pi-lens` | Real-time code feedback (LSP, linters) | pi-package, linter |
|
||||
| `@vanillagreen/pi-skills-manager` | Skills manager with /skill menu | pi-package, skills, manager |
|
||||
|
||||
## Community Resources
|
||||
|
||||
- [pi-package.rectorspace.com](https://pi-package.rectorspace.com) — Unofficial package index with stars, downloads, maintenance signals
|
||||
- [Anthropic Skills](https://github.com/anthropics/skills) — Document processing skills (docx, pdf, pptx, xlsx)
|
||||
- [skills.sh](https://skills.sh) — Skills directory (by Vercel Labs)
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/npx-skills/installation.md) — How to install from these resources
|
||||
* [Best Practices](/tools/npx-skills/best-practices.md) — How to contribute your own skills
|
||||
@@ -1,18 +0,0 @@
|
||||
# Npx Skills — Distribution & Installation
|
||||
|
||||
Tips for writing good skill descriptions, organizing files, and distributing pi packages on npm.
|
||||
|
||||
## Concept Files
|
||||
|
||||
| File | Type | Description |
|
||||
|------|------|-------------|
|
||||
| [best-practices.md](best-practices.md) | best-practices | Tips for writing good skill descriptions, organizing files, and distributing ... |
|
||||
| [ecosystem.md](ecosystem.md) | reference | GitHub repositories, npm packages, and community resources for the pi skills ... |
|
||||
| [installation.md](installation.md) | howto | Three methods for installing skills — pi install, npx-based setup tools, and ... |
|
||||
| [package-structure.md](package-structure.md) | reference | How pi packages bundle skills, extensions, prompts, and themes into a single ... |
|
||||
| [skill-commands.md](skill-commands.md) | reference | The /skill:name command system for explicitly loading and executing skills wi... |
|
||||
| [skill-file-structure.md](skill-file-structure.md) | reference | The directory structure of a skill — SKILL.md as the required entry point, wi... |
|
||||
| [skill-loading.md](skill-loading.md) | reference | The discovery flow, progressive disclosure pattern, and system prompt integra... |
|
||||
| [skills-spec.md](skills-spec.md) | reference | The Agent Skills standard that defines SKILL.md format, frontmatter fields, a... |
|
||||
| [skills-vs-extensions.md](skills-vs-extensions.md) | comparison | Side-by-side comparison of skills (markdown-based) vs extensions (TypeScript-... |
|
||||
|
||||
@@ -1,81 +0,0 @@
|
||||
---
|
||||
type: howto
|
||||
title: Installing Skills via npm / npx
|
||||
description: Three methods for installing skills — pi install, npx-based setup tools, and manual git clone.
|
||||
tags:
|
||||
- unverified
|
||||
- installation
|
||||
- npm
|
||||
- npx
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Installing Skills via NPM / Npx
|
||||
|
||||
## Method 1: Direct `pi install` (recommended)
|
||||
|
||||
```bash
|
||||
# Install a package containing skills
|
||||
pi install npm:pi-web-access
|
||||
pi install npm:@anton-kochev/pi-skills
|
||||
pi install npm:bigpowers
|
||||
pi install npm:@monopi/skills
|
||||
|
||||
# Install from GitHub (also works for packages with skills)
|
||||
pi install git:github.com/badlogic/pi-skills
|
||||
pi install https://github.com/badlogic/pi-skills
|
||||
|
||||
# Project-level install (goes to .pi/settings.json)
|
||||
pi install -l npm:pi-web-access
|
||||
|
||||
# Try without installing (current session only)
|
||||
pi -e npm:pi-web-access
|
||||
```
|
||||
|
||||
## Method 2: Npx-based setup tools
|
||||
|
||||
Some meta-installers provide one-command setup:
|
||||
|
||||
```bash
|
||||
# monopi: one-command setup for pi with skills, extensions, themes, etc.
|
||||
npx @monopi/monopi
|
||||
|
||||
# Pin a version
|
||||
npx @monopi/monopi --version 0.2.13
|
||||
|
||||
# Project-local install
|
||||
npx @monopi/monopi --local
|
||||
|
||||
# Remove all monopi packages
|
||||
npx @monopi/monopi --remove
|
||||
```
|
||||
|
||||
## Method 3: Manual clone (git repos)
|
||||
|
||||
```bash
|
||||
# Clone the official pi-skills collection
|
||||
git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills
|
||||
|
||||
# Or project-level
|
||||
git clone https://github.com/badlogic/pi-skills .pi/skills/pi-skills
|
||||
```
|
||||
|
||||
## Package Sources
|
||||
|
||||
| Source Type | Example | Notes |
|
||||
|-------------|---------|-------|
|
||||
| **npm** | `npm:@foo/bar@1.0.0` | Pinned versions, installed to `~/.pi/agent/npm/` |
|
||||
| **git** | `git:github.com/user/repo@v1` | Pinned to tags/commits, cloned to `~/.pi/agent/git/` |
|
||||
| **local** | `./relative/path` | Points to local directory, added without copying |
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Runtime dependencies belong in `dependencies` in `package.json`
|
||||
- Pi-provided packages (`@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`) as `peerDependencies` with `"*"` range
|
||||
- When pi installs from npm or git, it runs `npm install` automatically
|
||||
|
||||
## Related
|
||||
|
||||
* [Package Structure](/tools/npx-skills/package-structure.md) — How pi packages are structured for npm distribution
|
||||
* [Best Practices](/tools/npx-skills/best-practices.md) — Distribution tips for skill authors
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Pi Package Structure
|
||||
description: How pi packages bundle skills, extensions, prompts, and themes into a single npm package with a pi manifest.
|
||||
tags:
|
||||
- unverified
|
||||
- packages
|
||||
- npm
|
||||
- distribution
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Pi Packages — The Distribution Mechanism
|
||||
|
||||
Pi packages are npm packages that declare resources via a `pi` manifest in `package.json`. They are the primary way to distribute skills (along with extensions, prompts, and themes) through npm.
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
my-pi-package/
|
||||
├── package.json # npm metadata + pi manifest
|
||||
├── skills/ # Conventional directory (auto-discovered)
|
||||
│ ├── my-skill/
|
||||
│ │ └── SKILL.md
|
||||
│ └── another-skill/
|
||||
│ └── SKILL.md
|
||||
├── extensions/ # TypeScript extensions
|
||||
├── prompts/ # Prompt templates
|
||||
├── themes/ # TUI themes
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Package.json with pi Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-pi-package",
|
||||
"keywords": ["pi-package"],
|
||||
"pi": {
|
||||
"extensions": ["./extensions"],
|
||||
"skills": ["./skills"],
|
||||
"prompts": ["./prompts"],
|
||||
"themes": ["./themes"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Gallery Metadata
|
||||
|
||||
Packages tagged with `pi-package` appear on the [pi.dev/packages gallery](https://pi.dev/packages). Add preview media:
|
||||
|
||||
```json
|
||||
{
|
||||
"pi": {
|
||||
"skills": ["./skills"],
|
||||
"video": "https://example.com/demo.mp4",
|
||||
"image": "https://example.com/screenshot.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Two-Layer Model
|
||||
|
||||
```
|
||||
npm package (tagged pi-package)
|
||||
├── pi.skills manifest → points to ./skills/
|
||||
└── skills/
|
||||
├── brave-search/SKILL.md
|
||||
├── browser-tools/SKILL.md
|
||||
└── tdd-workflow/SKILL.md
|
||||
```
|
||||
|
||||
Skills are the **content** (SKILL.md + scripts). Pi packages are the **delivery mechanism** (npm tarball with a `pi` manifest).
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/npx-skills/installation.md) — How to install pi packages
|
||||
* [Skill File Structure](/tools/npx-skills/skill-file-structure.md) — What goes inside a skill
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skill Commands
|
||||
description: The /skill:name command system for explicitly loading and executing skills with optional arguments.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- commands
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Skill Commands (`/skill:name`)
|
||||
|
||||
Skills register as `/skill:name` commands:
|
||||
|
||||
```bash
|
||||
/skill:brave-search # Load and execute the skill
|
||||
/skill:pdf-tools extract # Load skill with arguments
|
||||
```
|
||||
|
||||
Arguments after the command are appended to the skill content as `User: <args>`.
|
||||
|
||||
Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enableSkillCommands": true
|
||||
}
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Skill Loading](../npx-skills/skill-loading.md) — How skills are normally loaded
|
||||
* [Npx Skills Overview](../npx-skills/index.md) — Settings and package control
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skill File Structure
|
||||
description: The directory structure of a skill — SKILL.md as the required entry point, with optional scripts, references, and assets directories.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- structure
|
||||
- SKILL.md
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Skill File Structure
|
||||
|
||||
A skill is a **directory** with a `SKILL.md` file. Everything else is freeform.
|
||||
|
||||
## Standard Structure
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Required: frontmatter + instructions
|
||||
├── scripts/ # Helper scripts (bash, js, python, etc.)
|
||||
│ ├── process.sh
|
||||
│ └── analyze.js
|
||||
├── references/ # Detailed docs loaded on-demand
|
||||
│ ├── api-reference.md
|
||||
│ └── FORMS.md
|
||||
├── assets/ # Templates, configs, binary data
|
||||
│ └── template.json
|
||||
├── config.json # Skill-specific configuration
|
||||
└── tests/ # Test scripts (optional)
|
||||
└── test_runner.sh
|
||||
```
|
||||
|
||||
## Real Example: zim-knowledge-base
|
||||
|
||||
```
|
||||
zim-knowledge-base/
|
||||
├── SKILL.md # Main skill instructions
|
||||
├── config.json # ZIM file path configuration
|
||||
├── scripts/
|
||||
│ ├── search.sh # Search ZIM file index
|
||||
│ ├── extract.sh # Extract article as HTML
|
||||
│ ├── list.sh # List article titles
|
||||
│ └── metadata.sh # Get article metadata
|
||||
└── tests/
|
||||
├── mock_zimdump.sh # Mock for testing
|
||||
├── test_runner.sh # Test harness
|
||||
└── test_zim_file.zim # Test fixture
|
||||
```
|
||||
|
||||
## Real Example: brave-search (from badlogic/pi-skills)
|
||||
|
||||
```
|
||||
brave-search/
|
||||
├── SKILL.md # Setup + usage instructions
|
||||
├── search.js # Brave Search API wrapper
|
||||
└── content.js # Page content extraction
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Skills Specification](/tools/npx-skills/skills-spec.md) — Frontmatter fields and requirements
|
||||
* [Best Practices](/tools/npx-skills/best-practices.md) — File organization tips
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: How Pi Loads Skills
|
||||
description: The discovery flow, progressive disclosure pattern, and system prompt integration for skills in pi.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- loading
|
||||
- progressive-disclosure
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# How the Pi Agent Loads and Uses Skills
|
||||
|
||||
## Discovery Flow
|
||||
|
||||
1. Pi scans all configured skill locations at startup
|
||||
2. Extracts names and descriptions from each `SKILL.md`
|
||||
3. Builds the system prompt with skill descriptions in XML format
|
||||
4. The LLM decides which skill(s) to activate based on the user's prompt
|
||||
5. When activated, the agent reads the full SKILL.md using the `read` tool
|
||||
|
||||
## Progressive Disclosure Pattern
|
||||
|
||||
```
|
||||
System prompt (always in context):
|
||||
- "Available skills: brave-search (Web search...), browser-tools (Browser automation...), ..."
|
||||
|
||||
User: "Search for information about React hooks"
|
||||
|
||||
Agent decides: activate brave-search
|
||||
Agent reads: ~/.pi/agent/skills/brave-search/SKILL.md (full file)
|
||||
Agent executes: {baseDir}/search.js "React hooks"
|
||||
```
|
||||
|
||||
## This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
|
||||
|
||||
## Related
|
||||
|
||||
* [Skills Specification](/tools/npx-skills/skills-spec.md) — What the agent sees in the system prompt
|
||||
* [Skill Commands](/tools/npx-skills/skill-commands.md) — The `/skill:name` override
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Agent Skills Specification
|
||||
description: The Agent Skills standard that defines SKILL.md format, frontmatter fields, and cross-agent compatibility.
|
||||
tags:
|
||||
- unverified
|
||||
- agent-skills
|
||||
- specification
|
||||
- npm
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Agent Skills Specification
|
||||
|
||||
Pi implements the [Agent Skills standard](https://agentskills.io/specification), warning about most violations but remaining lenient. The specification defines:
|
||||
|
||||
- A **frontmatter block** (YAML) at the top of `SKILL.md` with required `name` and `description` fields
|
||||
- A **Markdown body** with the skill's instructions
|
||||
- Optional subdirectories: `scripts/`, `references/`, `assets/`
|
||||
|
||||
The specification is designed to be **cross-agent-compatible**: skills written for pi work with Claude Code, Codex CLI, Amp, Droid, and other compatible agents.
|
||||
|
||||
## Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | **Yes** | Max 64 chars. Lowercase a-z, 0-9, hyphens only. No leading/trailing hyphens. No consecutive hyphens. |
|
||||
| `description` | **Yes** | Max 1024 chars. What the skill does and when to use it. **This is the only thing the agent sees when deciding whether to activate the skill.** |
|
||||
| `license` | No | License name or reference to bundled file. |
|
||||
| `compatibility` | No | Max 500 chars. Environment requirements. |
|
||||
| `metadata` | No | Arbitrary key-value mapping. |
|
||||
| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
|
||||
| `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. Users must use `/skill:name` explicitly. |
|
||||
|
||||
### Name Rules
|
||||
|
||||
Valid: `pdf-processing`, `data-analysis`, `code-review`
|
||||
Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
|
||||
|
||||
**Note:** Pi does not require the name to match the parent directory. The Agent Skills standard does, but that requirement is suboptimal for shared skill directories.
|
||||
|
||||
### Description Best Practices
|
||||
|
||||
The description determines when the agent loads the skill. Be specific.
|
||||
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
|
||||
```
|
||||
|
||||
**Poor:**
|
||||
```yaml
|
||||
description: Helps with PDFs.
|
||||
```
|
||||
|
||||
## Cross-Agent Compatibility
|
||||
|
||||
Skills follow a shared specification that works across:
|
||||
|
||||
- Pi (`~/.pi/agent/skills/`)
|
||||
- Claude Code (`~/.claude/skills/`)
|
||||
- Codex (`~/.codex/skills/`)
|
||||
- OpenCode (`~/.config/opencode/skills/`)
|
||||
- And [68+ other agents](/tools/vercel-labs-skills/agent-support.md)
|
||||
|
||||
## Related
|
||||
|
||||
* [Skill File Structure](/tools/npx-skills/skill-file-structure.md) — How to organize SKILL.md and its supporting files
|
||||
* [Ecosystem](/tools/npx-skills/ecosystem.md) — Where to find community skills
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills vs Extensions
|
||||
description: Side-by-side comparison of skills (markdown-based) vs extensions (TypeScript-based) for pi coding agent.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- extensions
|
||||
- comparison
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Skills vs Extensions
|
||||
|
||||
| Feature | Skills | Extensions |
|
||||
|---------|--------|------------|
|
||||
| **Format** | Markdown (`SKILL.md` + optional scripts) | TypeScript (`.ts` files) |
|
||||
| **Purpose** | Instructions for the LLM to follow | Code that intercepts events, registers tools/commands |
|
||||
| **Execution** | Agent reads and follows instructions | Runs in pi's Node.js runtime |
|
||||
| **Loading** | On-demand (progressive disclosure) | Always loaded at startup |
|
||||
| **Power** | Can instruct the agent to run anything | Full programmatic access to pi's API |
|
||||
| **Security** | Review content (instructs model) | Review code (runs arbitrary code) |
|
||||
| **Best for** | Domain knowledge, workflows, scripts | Permission gates, custom tools, event handling |
|
||||
| **Location** | `skills/` directory | `extensions/` directory |
|
||||
| **Can distribute via npm?** | Yes (via pi packages) | Yes (via pi packages) |
|
||||
|
||||
## When to Use Each
|
||||
|
||||
- **Skill**: You want to teach the agent a new workflow, provide domain expertise, or bundle helper scripts
|
||||
- **Extension**: You need to intercept tool calls, register new LLM-callable tools, modify system prompts programmatically, or add custom TUI components
|
||||
|
||||
## They Can Work Together
|
||||
|
||||
A pi package can contain both:
|
||||
|
||||
```json
|
||||
{
|
||||
"pi": {
|
||||
"extensions": ["./extensions"],
|
||||
"skills": ["./skills"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Example: `pi-web-access` provides both a web-search extension AND skill documentation for it.
|
||||
|
||||
## Related
|
||||
|
||||
* [Package Structure](/tools/npx-skills/package-structure.md) — How to bundle both in one npm package
|
||||
@@ -1,73 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: llama.cpp Server API Endpoints
|
||||
description: Complete reference for health check, model listing, chat completions, and native completion endpoints.
|
||||
tags:
|
||||
- unverified
|
||||
- ornith
|
||||
- api
|
||||
- llama.cpp
|
||||
- endpoints
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# API Endpoints
|
||||
|
||||
The llama.cpp server provides these endpoints:
|
||||
|
||||
## Health Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
## List Models
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/v1/models
|
||||
```
|
||||
|
||||
## Chat Completions (OpenAI-compatible)
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "frank-default-local",
|
||||
"messages": [...],
|
||||
"max_tokens": 100
|
||||
}'
|
||||
```
|
||||
|
||||
## Native Completion Endpoint
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/completion \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Hello, how are you?",
|
||||
"n_predict": 100
|
||||
}'
|
||||
```
|
||||
|
||||
## Model Features
|
||||
|
||||
### Reasoning/Thinking Blocks
|
||||
|
||||
Ornith models use `<think>...</think>` blocks for reasoning. The server automatically:
|
||||
- Detects and preserves reasoning content
|
||||
- Returns reasoning in `reasoning_content` field
|
||||
- Supports the `developer` role (or falls back to `system`)
|
||||
|
||||
### Chat Template
|
||||
|
||||
The model uses a specific chat template that supports:
|
||||
- System prompts
|
||||
- User/Assistant roles
|
||||
- Reasoning preservation
|
||||
|
||||
## Related
|
||||
|
||||
* [Pi Configuration](/tools/ornith-llama-cpp-setup/pi-configuration.md) — How pi connects to these endpoints
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — Starting the server
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: GPU Layer Offloading Guidelines
|
||||
description: How many GPU layers to offload based on your VRAM size for both Ornith 9B and 35B models.
|
||||
tags:
|
||||
- unverified
|
||||
- ornith
|
||||
- gpu
|
||||
- offloading
|
||||
- llama.cpp
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# GPU Layer Offloading
|
||||
|
||||
## For 9B Q4_K_M (5.63 GB):
|
||||
|
||||
- **8GB VRAM:** `-ngl 35-40` (fits most layers)
|
||||
- **12GB VRAM:** `-ngl 99` (all layers)
|
||||
- **16GB+ VRAM:** `-ngl 99` (all layers + room for large KV cache)
|
||||
|
||||
## For 35B Q4_K_M (~20 GB):
|
||||
|
||||
- **8GB VRAM:** `-ngl 10-14` (partial offload)
|
||||
- **12GB VRAM:** `-ngl 18-22` (partial offload)
|
||||
- **16GB VRAM:** `-ngl 28-32` (partial offload)
|
||||
- **24GB VRAM:** `-ngl 40-48` (majority of layers)
|
||||
- **40GB+ VRAM:** `-ngl 99` (all layers)
|
||||
|
||||
**Note:** The 35B model is a MoE architecture, so actual memory usage depends on which experts are activated.
|
||||
|
||||
## Context Window Considerations
|
||||
|
||||
- **9B model:** Supports up to 262,144 tokens
|
||||
- **35B model:** Supports up to 262,144 tokens
|
||||
- **KV Cache Memory:** Larger context windows require more VRAM/RAM for the key-value cache
|
||||
- 131K context: ~8-16 GB depending on model and quantization
|
||||
- 256K context: ~16-32 GB depending on model and quantization
|
||||
|
||||
**Recommendation:** Start with 131K context if you have limited VRAM, increase to 256K if you have headroom.
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — How to set the -ngl flag
|
||||
* [Model Specs](/tools/ornith-llama-cpp-setup/model-specs.md) — Memory requirements
|
||||
@@ -1,17 +0,0 @@
|
||||
# Ornith llama.cpp Setup
|
||||
|
||||
Complete reference for running Ornith-9B/35B MoE models with llama.cpp server on the workstation.
|
||||
|
||||
## Concept Files
|
||||
|
||||
| File | Type | Description |
|
||||
|------|------|-------------|
|
||||
| [api-endpoints.md](api-endpoints.md) | reference | Complete reference for health check, model listing, chat completions, and nat... |
|
||||
| [gpu-offloading.md](gpu-offloading.md) | reference | How many GPU layers to offload based on your VRAM size for both Ornith 9B and... |
|
||||
| [installation.md](installation.md) | howto | Step-by-step setup — clone and build llama.cpp, download models, start the se... |
|
||||
| [model-specs.md](model-specs.md) | reference | Specifications for Ornith-1.0-9B dense and Ornith-1.0-35B MoE models — contex... |
|
||||
| [performance.md](performance.md) | reference | Token throughput benchmarks for Ornith 9B and 35B models with GPU vs CPU infe... |
|
||||
| [pi-configuration.md](pi-configuration.md) | howto | How to add Ornith models to models.json so pi can use the local llama.cpp ser... |
|
||||
| [systemd-service.md](systemd-service.md) | howto | Set up llama.cpp server as a background service with systemd for persistent o... |
|
||||
| [troubleshooting.md](troubleshooting.md) | howto | Common errors — CUDA OOM, segfaults, model not responding, poor performance —... |
|
||||
|
||||
@@ -1,97 +0,0 @@
|
||||
---
|
||||
type: howto
|
||||
title: Installing Ornith + llama.cpp
|
||||
description: Step-by-step setup — clone and build llama.cpp, download models, start the server, verify it works.
|
||||
tags:
|
||||
- ornith
|
||||
- installation
|
||||
- llama.cpp
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Installation
|
||||
|
||||
## 1. Clone and Build llama.cpp
|
||||
|
||||
```bash
|
||||
cd ~/GitPackages
|
||||
git clone https://github.com/ggerganov/llama.cpp
|
||||
cd llama.cpp
|
||||
cmake -B build -DLLAMA_CUDA=ON
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
## 2. Download the Model
|
||||
|
||||
```bash
|
||||
mkdir -p ~/models/ornith
|
||||
cd ~/models/ornith
|
||||
|
||||
# For 9B model (faster, less memory)
|
||||
wget https://huggingface.co/ornith-ai/Ornith-1.0-9B-GGUF/resolve/main/ornith-1.0-9b-Q4_K_M.gguf
|
||||
|
||||
# OR for 35B MoE model (better performance, more memory)
|
||||
wget https://huggingface.co/ornith-ai/Ornith-1.0-35B-GGUF/resolve/main/ornith-1.0-35b-Q4_K_M.gguf
|
||||
```
|
||||
|
||||
## 3. Start the Server
|
||||
|
||||
**For 9B model with full GPU offload (8GB+ VRAM):**
|
||||
```bash
|
||||
cd ~/GitPackages/llama.cpp
|
||||
./build/bin/llama-server \
|
||||
-m ~/models/ornith/ornith-1.0-9b-Q4_K_M.gguf \
|
||||
-c 262144 \
|
||||
-ngl 99 \
|
||||
--host 0.0.0.0 \
|
||||
--port 8080
|
||||
```
|
||||
|
||||
**For 35B MoE model with partial GPU offload (8GB VRAM example):**
|
||||
```bash
|
||||
cd ~/GitPackages/llama.cpp
|
||||
./build/bin/llama-server \
|
||||
-m ~/models/ornith/ornith-1.0-35b-Q4_K_M.gguf \
|
||||
-c 131072 \
|
||||
-ngl 12 \
|
||||
--host 0.0.0.0 \
|
||||
--port 8080
|
||||
```
|
||||
|
||||
**Key Parameters:**
|
||||
- `-m`: Path to GGUF model file
|
||||
- `-c` / `--ctx-size`: Context window size (131072 or 262144)
|
||||
- `-ngl` / `--n-gpu-layers`: Number of layers to offload to GPU
|
||||
- 99 = all layers
|
||||
- Lower values = more CPU inference
|
||||
- `--host`: Bind address (0.0.0.0 for all interfaces, 127.0.0.1 for local only)
|
||||
- `--port`: Server port (default 8080)
|
||||
|
||||
## 4. Verify Server is Running
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
# Expected: {"status":"ok"}
|
||||
```
|
||||
|
||||
## 5. Test the Model
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:8080/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "frank-default-local",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Hello, what is 2+2?"}
|
||||
],
|
||||
"max_tokens": 150,
|
||||
"temperature": 0.7
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Model Specs](/tools/ornith-llama-cpp-setup/model-specs.md) — Model options and quantization
|
||||
* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — Tuning GPU layer counts
|
||||
* [Pi Configuration](/tools/ornith-llama-cpp-setup/pi-configuration.md) — Adding to models.json
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Ornith Model Specifications
|
||||
description: Specifications for Ornith-1.0-9B dense and Ornith-1.0-35B MoE models — context length, quantization options, memory requirements.
|
||||
tags:
|
||||
- ornith
|
||||
- models
|
||||
- llama.cpp
|
||||
- GGUF
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Model Specifications
|
||||
|
||||
## Ornith-1.0-9B-GGUF
|
||||
|
||||
- **Source:** https://huggingface.co/ornith-ai/Ornith-1.0-9B-GGUF
|
||||
- **Architecture:** Dense ~9B model
|
||||
- **Context Length:** 262,144 tokens (256K)
|
||||
- **Quantization Options:**
|
||||
- Q4_K_M: 5.3 GB (recommended for most systems)
|
||||
- Q5_K_M: 6.47 GB
|
||||
- Q6_K: 7.36 GB
|
||||
- Q8_0: 9.53 GB
|
||||
- bf16: 17.9 GB
|
||||
|
||||
## Ornith-1.0-35B-GGUF (MoE)
|
||||
|
||||
- **Source:** https://huggingface.co/ornith-ai/Ornith-1.0-35B-GGUF
|
||||
- **Architecture:** 35B MoE (Mixture of Experts)
|
||||
- **Context Length:** 262,144 tokens (256K)
|
||||
- **Quantization Options:**
|
||||
- Q4_K_M: 20 GB (recommended)
|
||||
- Other quantizations available
|
||||
|
||||
**Note:** No fp4 quantization exists for these models. Q4_K_M is the lightest quantization.
|
||||
|
||||
## Comparison: 9B vs 35B MoE
|
||||
|
||||
| Aspect | 9B Dense | 35B MoE |
|
||||
|--------|----------|---------|
|
||||
| **Memory (Q4)** | 5.3 GB | 20 GB |
|
||||
| **VRAM for Full GPU** | 8 GB | 24-40 GB |
|
||||
| **Speed (GPU)** | Faster | Slower but better quality |
|
||||
| **Quality** | Good | Excellent |
|
||||
| **Context** | 256K | 256K |
|
||||
| **Best For** | Quick tasks, limited RAM | Complex reasoning, best quality |
|
||||
|
||||
## Requirements
|
||||
|
||||
### Hardware
|
||||
- **RAM:** Minimum 16GB for 9B model, 32GB+ for 35B model
|
||||
- **GPU** (optional but recommended):
|
||||
- 9B Q4: 6-8GB VRAM for full GPU offload
|
||||
- 35B Q4: 24GB+ VRAM for full GPU offload
|
||||
|
||||
### Software
|
||||
- llama.cpp built with CUDA support (for GPU acceleration)
|
||||
- Git (for cloning llama.cpp repo)
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — How to set up the server
|
||||
* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — Layer allocation by VRAM
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Performance Benchmarks
|
||||
description: Token throughput benchmarks for Ornith 9B and 35B models with GPU vs CPU inference.
|
||||
tags:
|
||||
- ornith
|
||||
- performance
|
||||
- benchmarks
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Performance
|
||||
# Performance
|
||||
|
||||
## 9B Model:
|
||||
|
||||
- **Prompt Processing:** ~10-15 tokens/sec (CPU), ~50-100 tokens/sec (GPU)
|
||||
- **Generation:** ~8-12 tokens/sec (CPU), ~40-80 tokens/sec (GPU)
|
||||
|
||||
## 35B MoE Model:
|
||||
|
||||
- **Prompt Processing:** ~5-8 tokens/sec (CPU+GPU mix), ~30-50 tokens/sec (full GPU)
|
||||
- **Generation:** ~4-8 tokens/sec (CPU+GPU mix), ~20-40 tokens/sec (full GPU)
|
||||
|
||||
**Note:** MoE models can be slower due to expert routing overhead, but provide better quality.
|
||||
|
||||
## Tuning Tips
|
||||
|
||||
1. **Increase GPU layers** (`-ngl`) for better speed
|
||||
2. **Enable Flash Attention:** `--flash-attn on` (if supported)
|
||||
3. **Use a smaller quantization** (Q4_K_M instead of Q8_0)
|
||||
4. **Reduce context window size** if memory-bound
|
||||
5. **KV Cache Quantization:** `--cache-type-k q8_0` to reduce KV cache memory
|
||||
|
||||
## Related
|
||||
|
||||
* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — Optimize GPU layers for your hardware
|
||||
* [Troubleshooting](/tools/ornith-llama-cpp-setup/troubleshooting.md) — Fix performance issues
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
type: howto
|
||||
title: Pi Configuration for Ornith Models
|
||||
description: How to add Ornith models to models.json so pi can use the local llama.cpp server as a provider.
|
||||
tags:
|
||||
- unverified
|
||||
- ornith
|
||||
- pi
|
||||
- models.json
|
||||
- configuration
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Pi Configuration
|
||||
|
||||
Add to `~/.pi/agent/models.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"llamacpp (local-ornith)": {
|
||||
"baseUrl": "http://localhost:8080/v1",
|
||||
"api": "openai-completions",
|
||||
"apiKey": "EMPTY",
|
||||
"compat": {
|
||||
"supportsDeveloperRole": false,
|
||||
"supportsReasoningEffort": false
|
||||
},
|
||||
"models": [
|
||||
{
|
||||
"id": "frank-default-local",
|
||||
"name": "Ornith-1.0-35B-Q4_K_M (Local)",
|
||||
"contextWindow": 131072,
|
||||
"reasoning": true,
|
||||
"thinkingLevelMap": {
|
||||
"max": "xhigh"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important Compatibility Settings:**
|
||||
|
||||
- `supportsDeveloperRole: false` — The server does not support the `developer` role, uses `system` instead
|
||||
- `supportsReasoningEffort: false` — The server does not support the `reasoning_effort` parameter
|
||||
- `reasoning: true` — Model supports reasoning/thinking blocks
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — Get the server running first
|
||||
* [API Endpoints](/tools/ornith-llama-cpp-setup/api-endpoints.md) — The endpoints this configuration targets
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
type: howto
|
||||
title: Running Ornith as a Systemd Service
|
||||
description: Set up llama.cpp server as a background service with systemd for persistent operation.
|
||||
tags:
|
||||
- unverified
|
||||
- ornith
|
||||
- systemd
|
||||
- service
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Systemd Service
|
||||
|
||||
## Using nohup:
|
||||
|
||||
```bash
|
||||
nohup ~/GitPackages/llama.cpp/build/bin/llama-server \
|
||||
-m ~/models/ornith/ornith-1.0-35b-Q4_K_M.gguf \
|
||||
-c 131072 -ngl 12 \
|
||||
--host 0.0.0.0 --port 8080 \
|
||||
> ~/logs/llama-server.log 2>&1 &
|
||||
```
|
||||
|
||||
## Using systemd (advanced):
|
||||
|
||||
Create `/etc/systemd/system/llama-server.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=llama.cpp Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=dank
|
||||
ExecStart=/home/dank/GitPackages/llama.cpp/build/bin/llama-server \
|
||||
-m /home/dank/models/ornith/ornith-1.0-35b-Q4_K_M.gguf \
|
||||
-c 131072 -ngl 12 \
|
||||
--host 0.0.0.0 --port 8080
|
||||
Restart=on-failure
|
||||
WorkingDirectory=/home/dank/GitPackages/llama.cpp
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable llama-server
|
||||
sudo systemctl start llama-server
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — The server setup this service wraps
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
type: howto
|
||||
title: Troubleshooting Ornith + llama.cpp
|
||||
description: Common errors — CUDA OOM, segfaults, model not responding, poor performance — and their fixes.
|
||||
tags:
|
||||
- unverified
|
||||
- ornith
|
||||
- troubleshooting
|
||||
- llama.cpp
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
## CUDA Out of Memory
|
||||
|
||||
```
|
||||
Error: cudaMalloc failed: out of memory
|
||||
```
|
||||
|
||||
**Solution:** Reduce `-ngl` value to offload fewer layers to GPU.
|
||||
|
||||
## Segmentation Fault
|
||||
|
||||
```
|
||||
Segmentation fault (core dumped)
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
1. Reduce context size (`-c` parameter)
|
||||
2. Reduce GPU layers (`-ngl`)
|
||||
3. Check if model file is corrupted
|
||||
|
||||
## Model Not Responding
|
||||
|
||||
```
|
||||
curl: (7) Failed to connect to localhost port 8080
|
||||
```
|
||||
|
||||
**Solution:** Check if server is running:
|
||||
```bash
|
||||
ps aux | grep llama-server
|
||||
tail -f ~/logs/llama-server.log
|
||||
```
|
||||
|
||||
## Poor Performance
|
||||
|
||||
**Solutions:**
|
||||
1. Increase GPU layers (`-ngl`)
|
||||
2. Enable Flash Attention: `--flash-attn on` (if supported)
|
||||
3. Use a smaller quantization (Q4_K_M instead of Q8_0)
|
||||
4. Reduce context window size
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **Local Server:** By default, binds to localhost (127.0.0.1)
|
||||
- **Network Exposure:** If binding to 0.0.0.0, consider:
|
||||
- Adding authentication (`--api-key`)
|
||||
- Using a firewall to restrict access
|
||||
- Running behind a reverse proxy with TLS
|
||||
|
||||
```bash
|
||||
# Add API key authentication
|
||||
./build/bin/llama-server ... --api-key your-secret-key
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — The commands that might be causing issues
|
||||
* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — GPU configuration
|
||||
@@ -1,84 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Agent Support Matrix
|
||||
description: Complete list of 68+ supported coding agents, their --agent flags, and installation paths (project and global).
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- agents
|
||||
- compatibility
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Agent Support
|
||||
|
||||
The CLI supports **68+ agents**. It automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select which agents to install to.
|
||||
|
||||
## Full Agent Path Table
|
||||
|
||||
| Agent | `--agent` | Project Path | Global Path |
|
||||
|-------|-----------|--------------|-------------|
|
||||
| Amp, Replit, Universal | `amp`, `replit`, `universal` | `.agents/skills/` | `~/.config/agents/skills/` |
|
||||
| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
|
||||
| Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
|
||||
| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
|
||||
| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
|
||||
| Cline, Dexto, Kimi Code CLI, Loaf, Warp, Zed | `cline`, `dexto`, `kimi-code-cli`, `loaf`, `warp`, `zed` | `.agents/skills/` | `~/.agents/skills/` |
|
||||
| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
|
||||
| GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` |
|
||||
| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
|
||||
| Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
|
||||
| Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
|
||||
| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
|
||||
| Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
|
||||
| Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
|
||||
| OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
|
||||
| Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
|
||||
| Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
|
||||
| Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
|
||||
| iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
|
||||
| Deep Agents | `deepagents` | `.agents/skills/` | `~/.deepagents/agent/skills/` |
|
||||
| Droid / Factory AI | `droid` | `.factory/skills/` | `~/.factory/skills/` |
|
||||
| Firebender | `firebender` | `.agents/skills/` | `~/.firebender/skills/` |
|
||||
| Devin for Terminal | `devin` | `.devin/skills/` | `~/.config/devin/skills/` |
|
||||
| Kilo Code | `kilo` | `.kilocode/skills/` | `~/.kilocode/skills/` |
|
||||
| Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
|
||||
| Anthropic Antigravity | `antigravity` | `.agents/skills/` | `~/.gemini/antigravity/skills/` |
|
||||
| Jazz | `jazz` | `.jazz/skills/` | `~/.jazz/skills/` |
|
||||
| Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
|
||||
| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
|
||||
| Lingma | `lingma` | `.lingma/skills/` | `~/.lingma/skills/` |
|
||||
| Moxby | `moxby` | `.moxby/skills/` | `~/.moxby/skills/` |
|
||||
| Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
|
||||
| Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
|
||||
| AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |
|
||||
| Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
|
||||
| AiderDesk | `aider-desk` | `.aider-desk/skills/` | `~/.aider-desk/skills/` |
|
||||
| IBM Bob | `bob` | `.bob/skills/` | `~/.bob/skills/` |
|
||||
| CodeArts Agent | `codearts-agent` | `.codeartsdoer/skills/` | `~/.codeartsdoer/skills/` |
|
||||
| CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
|
||||
| Codemaker | `codemaker` | `.codemaker/skills/` | `~/.codemaker/skills/` |
|
||||
| Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
|
||||
| Cortex Code | `cortex` | `.cortex/skills/` | `~/.snowflake/cortex/skills/` |
|
||||
| Eve | `eve` | `agent/skills/` | N/A (project-only) |
|
||||
| ForgeCode | `forgecode` | `.forge/skills/` | `~/.forge/skills/` |
|
||||
| Hermes Agent | `hermes-agent` | `.hermes/skills/` | `~/.hermes/skills/` |
|
||||
| inference.sh | `inference-sh` | `.inferencesh/skills/` | `~/.inferencesh/skills/` |
|
||||
| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
|
||||
| MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
|
||||
| Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
|
||||
| Ona | `ona` | `.ona/skills/` | `~/.ona/skills/` |
|
||||
| PromptScript | `promptscript` | `.agents/skills/` | N/A (project-only) |
|
||||
| Reasonix | `reasonix` | `.reasonix/skills/` | `~/.reasonix/skills/` |
|
||||
| Rovo Dev | `rovodev` | `.rovodev/skills/` | `~/.rovodev/skills/` |
|
||||
| Tabnine CLI | `tabnine-cli` | `.tabnine/agent/skills/` | `~/.tabnine/agent/skills/` |
|
||||
| Terramind | `terramind` | `.terramind/skills/` | `~/.terramind/skills/` |
|
||||
| Tinycloud | `tinycloud` | `.tinycloud/skills/` | `~/.tinycloud/skills/` |
|
||||
| Zencoder, Zenflow | `zencoder`, `zenflow` | `.zencoder/skills/` | `~/.zencoder/skills/` |
|
||||
|
||||
> **Kiro CLI users:** The default agent automatically loads skills from `.kiro/skills/` and `~/.kiro/skills/` — no configuration needed.
|
||||
|
||||
## Related
|
||||
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — Using the `--agent` flag with commands
|
||||
@@ -1,116 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Commands
|
||||
description: Complete reference for all skills CLI commands — add, use, list, find, update, remove, init, experimental_install, experimental_sync.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- cli
|
||||
- commands
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Commands Reference
|
||||
|
||||
## `skills add` — Install Skills
|
||||
|
||||
Install skills from a source (git repo, URL, or local path) into your agent directories.
|
||||
|
||||
```bash
|
||||
npx skills add <source> [options]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `-g, --global` | Install to user directory (`~/`) instead of project (`./`) |
|
||||
| `-a, --agent <agents...>` | Target specific agents |
|
||||
| `-s, --skill <skills...>` | Install specific skills by name. Use `'*'` for all. |
|
||||
| `-l, --list` | List available skills without installing |
|
||||
| `--copy` | Copy files instead of symlinking |
|
||||
| `-y, --yes` | Skip all confirmation prompts |
|
||||
| `--all` | Install all skills to all agents without prompts |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
npx skills add vercel-labs/agent-skills --list
|
||||
npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
|
||||
npx skills add vercel-labs/agent-skills -a claude-code -a opencode
|
||||
npx skills add vercel-labs/agent-skills --all
|
||||
```
|
||||
|
||||
## `skills use` — Use Without Installing
|
||||
|
||||
Generate a prompt for one skill, or start a supported coding agent interactively with the skill loaded.
|
||||
|
||||
```bash
|
||||
npx skills use <source> [options]
|
||||
# Generate prompt only
|
||||
npx skills use vercel-labs/agent-skills@web-design-guidelines | claude
|
||||
# Use with specific agent
|
||||
npx skills use vercel-labs/agent-skills --skill web-design-guidelines --agent claude-code
|
||||
```
|
||||
|
||||
## `skills list` (alias: `ls`) — List Installed Skills
|
||||
|
||||
```bash
|
||||
npx skills list
|
||||
npx skills ls -g # Global only
|
||||
npx skills ls -a claude-code -a cursor
|
||||
```
|
||||
|
||||
## `skills find` — Search for Skills
|
||||
|
||||
```bash
|
||||
npx skills find # Interactive search
|
||||
npx skills find typescript # Search by keyword
|
||||
npx skills find react --owner vercel
|
||||
```
|
||||
|
||||
## `skills update` — Update Installed Skills
|
||||
|
||||
```bash
|
||||
npx skills update # All skills (interactive)
|
||||
npx skills update my-skill # Single skill
|
||||
npx skills update -g # Global only
|
||||
npx skills update -y # Non-interactive
|
||||
```
|
||||
|
||||
## `skills remove` (alias: `rm`) — Remove Installed Skills
|
||||
|
||||
```bash
|
||||
npx skills remove # Interactive
|
||||
npx skills remove web-design-guidelines
|
||||
npx skills remove --all # Remove everything
|
||||
```
|
||||
|
||||
## `skills init` — Create a New SKILL.md Template
|
||||
|
||||
```bash
|
||||
npx skills init # In current directory
|
||||
npx skills init my-skill # In a subdirectory
|
||||
```
|
||||
|
||||
## `skills experimental_install` — Restore from Lock File
|
||||
|
||||
```bash
|
||||
npx skills experimental_install
|
||||
```
|
||||
|
||||
## Aliases
|
||||
|
||||
| Alias | Full Command |
|
||||
|-------|-------------|
|
||||
| `skills a` | `skills add` |
|
||||
| `skills i` | `skills experimental_install` |
|
||||
| `skills install` (no args) | `skills experimental_install` |
|
||||
| `skills ls` | `skills list` |
|
||||
| `skills rm` | `skills remove` |
|
||||
|
||||
## Related
|
||||
|
||||
* [Source Formats](/tools/vercel-labs-skills/source-formats.md) — What sources you can use with add/use
|
||||
* [Installation Scope](/tools/vercel-labs-skills/installation-scope.md) — Global vs project
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Environment Variables
|
||||
description: Environment variables — INSTALL_INTERNAL_SKILLS, DISABLE_TELEMETRY, DO_NOT_TRACK.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- environment
|
||||
- telemetry
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` |
|
||||
| `DISABLE_TELEMETRY` | Set to disable anonymous usage telemetry |
|
||||
| `DO_NOT_TRACK` | Alternative way to disable telemetry |
|
||||
|
||||
```bash
|
||||
# Install internal skills
|
||||
INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list
|
||||
```
|
||||
|
||||
## Telemetry
|
||||
|
||||
The CLI collects anonymous usage data to help improve the tool. No personal information is collected. Telemetry is automatically disabled in CI environments.
|
||||
|
||||
## Related
|
||||
|
||||
* [SKILL.md Format](/tools/vercel-labs-skills/skill-format.md) — `metadata.internal: true`
|
||||
@@ -1,19 +0,0 @@
|
||||
# Vercel Labs `skills` CLI
|
||||
|
||||
Complete list of 68+ supported coding agents, their --agent flags, and installation paths (project and global).
|
||||
|
||||
## Concept Files
|
||||
|
||||
| File | Type | Description |
|
||||
|------|------|-------------|
|
||||
| [agent-support.md](agent-support.md) | reference | Complete list of 68+ supported coding agents, their --agent flags, and instal... |
|
||||
| [commands.md](commands.md) | reference | Complete reference for all skills CLI commands — add, use, list, find, update... |
|
||||
| [env-variables.md](env-variables.md) | reference | Environment variables — INSTALL_INTERNAL_SKILLS, DISABLE_TELEMETRY, DO_NOT_TR... |
|
||||
| [installation-scope.md](installation-scope.md) | reference | Project vs global installation, symlink vs copy methods. |
|
||||
| [lock-file.md](lock-file.md) | reference | Version pinning and update checking via global and local lock files (.skill-l... |
|
||||
| [related-links.md](related-links.md) | reference | Links to the Agent Skills specification, skills directory, integration guide,... |
|
||||
| [skill-discovery.md](skill-discovery.md) | reference | How the skills CLI discovers SKILL.md files in repositories — flat layout, ca... |
|
||||
| [skill-format.md](skill-format.md) | reference | The required frontmatter fields, optional fields, internal skills, and struct... |
|
||||
| [skill-store-wiring.md](skill-store-wiring.md) | reference | How omp's agent/skills directory is symlinked into the skills CLI global store, and where lockfile provenance lives. |
|
||||
| [source-formats.md](source-formats.md) | reference | All accepted source formats for skills add and use — GitHub shorthand, full U... |
|
||||
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Installation Scope
|
||||
description: Project vs global installation, symlink vs copy methods.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- installation
|
||||
- scope
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Installation Scope
|
||||
|
||||
## Project vs Global
|
||||
|
||||
| Scope | Flag | Location | Use Case |
|
||||
|-------|------|----------|----------|
|
||||
| **Project** | _(default)_ | `./<agent>/skills/` | Committed with your project, shared with team |
|
||||
| **Global** | `-g` | `~/<agent>/skills/` | Available across all projects |
|
||||
|
||||
## Symlink vs Copy
|
||||
|
||||
When installing interactively, you can choose:
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| **Symlink** _(Recommended)_ | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. |
|
||||
| **Copy** | Creates independent copies for each agent. Use when symlinks are not supported. |
|
||||
|
||||
Use `--copy` to force copy mode.
|
||||
|
||||
## Related
|
||||
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — add, use, list, remove commands
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Lock File System
|
||||
description: Version pinning and update checking via global and local lock files (.skill-lock.json and skills-lock.json).
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- lockfile
|
||||
- versioning
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Lock File System
|
||||
|
||||
The `skills` CLI uses a lock file system for version pinning and update checking.
|
||||
|
||||
## Lock File Locations
|
||||
|
||||
| Type | Path | Scope |
|
||||
|------|------|-------|
|
||||
| **Global lock** | `~/.agents/.skill-lock.json` | Global (user-wide) |
|
||||
| **Local lock** | `skills-lock.json` | Project (checked into version control) |
|
||||
|
||||
## How `skills check` and `skills update` Work
|
||||
|
||||
1. Read `~/.agents/.skill-lock.json` for installed skills
|
||||
2. Filter to GitHub-backed skills that have both `skillFolderHash` and `skillPath`
|
||||
3. For each skill, call `fetchSkillFolderHash(source, skillPath, token)`
|
||||
- Optional auth token from `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`
|
||||
4. `fetchSkillFolderHash` calls GitHub Trees API (`/git/trees/<branch>?recursive=1` for `main`, then `master` fallback)
|
||||
5. Compare latest folder tree SHA with lock file `skillFolderHash`; mismatch means update available
|
||||
6. `skills update` reinstalls changed skills by invoking the current CLI directly
|
||||
|
||||
## Lock File Format
|
||||
|
||||
- **Version:** v3
|
||||
- **Key field:** `skillFolderHash` — GitHub tree SHA for the skill folder
|
||||
- **Compatibility:** If reading an older lock file version, it is wiped. Users must reinstall skills to populate the new format.
|
||||
|
||||
## Related
|
||||
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — check, update, experimental_install
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Vercel Labs Skills — Related Links
|
||||
description: Links to the Agent Skills specification, skills directory, integration guide, and agent-specific skill documentation.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- links
|
||||
- resources
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Related Links
|
||||
|
||||
## Specification & Ecosystem
|
||||
|
||||
| Resource | URL |
|
||||
|----------|-----|
|
||||
| [Agent Skills Specification](https://agentskills.io) | agentskills.io/specification |
|
||||
| [Skills Directory](https://skills.sh) | skills.sh |
|
||||
| [Agent Skills Integration Guide](https://agentskills.io/integrate-skills) | agentskills.io/integrate-skills |
|
||||
| [Vercel Agent Skills Repository](https://github.com/vercel-labs/agent-skills) | github.com/vercel-labs/agent-skills |
|
||||
|
||||
## Agent-Specific Skill Documentation
|
||||
|
||||
| Agent | Documentation |
|
||||
|-------|--------------|
|
||||
| Amp | [Amp Skills Documentation](https://ampcode.com/manual#agent-skills) |
|
||||
| Claude Code | [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills) |
|
||||
| Codex | [Codex Skills Documentation](https://developers.openai.com/codex/skills) (url unreachable 2026-08-28) |
|
||||
| Cursor | [Cursor Skills Documentation](https://cursor.com/docs/context/skills) |
|
||||
| Gemini CLI | [Gemini CLI Skills Documentation](https://geminicli.com/docs/cli/skills/) (url unreachable 2026-08-28) |
|
||||
| GitHub Copilot | [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) |
|
||||
| OpenCode | [OpenCode Skills Documentation](https://opencode.ai/docs/skills) (url unreachable 2026-08-28) |
|
||||
| OpenHands | [OpenHands Skills Documentation](https://docs.openhands.ai/modules/usage/how-to/using-skills) (url unreachable 2026-08-28) |
|
||||
| Pi | [Pi Skills Documentation](https://github.com/earendil-works/pi) |
|
||||
| Roo Code | [Roo Code Skills Documentation](https://docs.roocode.com/features/skills) (url unreachable 2026-08-28) |
|
||||
| Windsurf | [Windsurf](https://www.codeium.com/windsurf) (url unreachable 2026-08-28) |
|
||||
|
||||
## Related
|
||||
|
||||
* [Agent Support](/tools/vercel-labs-skills/agent-support.md) — Full list of 68+ supported agents
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Skill Discovery
|
||||
description: How the skills CLI discovers SKILL.md files in repositories — flat layout, catalog layout, plugin manifests.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- discovery
|
||||
- repository
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Skill Discovery
|
||||
|
||||
The CLI searches for skills in these locations within a repository. Each skill container directory is walked:
|
||||
|
||||
- **One level deep** for the common flat layout: `skills/<name>/SKILL.md`
|
||||
- **One extra level deep** for catalog layouts: `skills/<category>/<name>/SKILL.md`
|
||||
|
||||
A `SKILL.md` discovered at the shallower level shadows anything nested below it. Use `--full-depth` to also discover `SKILL.md` files outside these container directories.
|
||||
|
||||
## Standard Discovery Locations
|
||||
|
||||
- `SKILL.md` in root directory (if present)
|
||||
- `skills/`
|
||||
- `skills/.curated/`
|
||||
- `skills/.experimental/`
|
||||
- `skills/.system/`
|
||||
- `.agents/skills/`
|
||||
- `.claude/skills/`
|
||||
- `.goose/skills/`
|
||||
- `.openhands/skills/`
|
||||
- `.pi/skills/`
|
||||
- And many more per-agent directories (see [Agent Support](/tools/vercel-labs-skills/agent-support.md))
|
||||
|
||||
## Plugin Manifest Discovery
|
||||
|
||||
If `.claude-plugin/marketplace.json` or `.claude-plugin/plugin.json` exists, skills declared in those files are also discovered. This enables compatibility with the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem.
|
||||
|
||||
Example `marketplace.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": { "pluginRoot": "./plugins" },
|
||||
"plugins": [
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"source": "my-plugin",
|
||||
"skills": ["./skills/review", "./skills/test"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Skill paths declared in a manifest are searched at their declared depth.
|
||||
|
||||
If no skills are found in standard locations, a **recursive search** is performed as a fallback.
|
||||
|
||||
## Related
|
||||
|
||||
* [SKILL.md Format](/tools/vercel-labs-skills/skill-format.md) — What a discovered skill looks like
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — add and use commands
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: SKILL.md Format
|
||||
description: The required frontmatter fields, optional fields, internal skills, and structure for SKILL.md files.
|
||||
tags:
|
||||
- skills
|
||||
- SKILL.md
|
||||
- format
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
|
||||
# SKILL.md Format
|
||||
|
||||
Skills are directories containing a `SKILL.md` file with YAML frontmatter.
|
||||
|
||||
## Basic Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What this skill does and when to use it
|
||||
---
|
||||
|
||||
# My Skill
|
||||
|
||||
Instructions for the agent to follow when this skill is activated.
|
||||
|
||||
## When to Use
|
||||
|
||||
Describe the scenarios where this skill is used.
|
||||
|
||||
## Steps
|
||||
|
||||
1. First, do this
|
||||
2. Then, do that
|
||||
```
|
||||
|
||||
## Required Frontmatter Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `name` | string | Unique identifier (lowercase, hyphens allowed) |
|
||||
| `description` | string | Brief explanation of what the skill does |
|
||||
|
||||
## Optional Frontmatter Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `metadata.internal` | boolean | Set to `true` to hide the skill from normal discovery. Requires `INSTALL_INTERNAL_SKILLS=1` |
|
||||
| `license` | string | License name or reference to bundled file |
|
||||
| `compatibility` | string | Environment requirements (max 500 chars) |
|
||||
| `metadata` | object | Arbitrary key-value mapping |
|
||||
| `allowed-tools` | string | Space-delimited list of pre-approved tools (experimental) |
|
||||
| `disable-model-invocation` | boolean | When `true`, skill is hidden from system prompt. Users must use `/skill:name` explicitly |
|
||||
|
||||
## Internal Skills Example
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-internal-skill
|
||||
description: An internal skill not shown by default
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Skill Discovery](/tools/vercel-labs-skills/skill-discovery.md) — How skills are discovered in repos
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — `skills init` to create new skills
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Source Formats
|
||||
description: All accepted source formats for skills add and use — GitHub shorthand, full URLs, GitLab, git URLs, local paths.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- sources
|
||||
- git
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Source Formats
|
||||
|
||||
The `skills` CLI accepts multiple source formats for the `add` and `use` commands:
|
||||
|
||||
```bash
|
||||
# GitHub shorthand (owner/repo)
|
||||
npx skills add vercel-labs/agent-skills
|
||||
|
||||
# Full GitHub URL
|
||||
npx skills add https://github.com/vercel-labs/agent-skills
|
||||
|
||||
# Direct path to a skill in a repo
|
||||
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
|
||||
|
||||
# GitLab URL
|
||||
npx skills add https://gitlab.com/org/repo
|
||||
|
||||
# Any git URL
|
||||
npx skills add git@github.com:vercel-labs/agent-skills.git
|
||||
|
||||
# Local path
|
||||
npx skills add ./my-local-skills
|
||||
```
|
||||
|
||||
The source parser (`src/source-parser.ts`) handles all these formats, cloning repos as needed and resolving skill directories.
|
||||
|
||||
## Related
|
||||
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — add and use commands
|
||||
* [Skill Discovery](/tools/vercel-labs-skills/skill-discovery.md) — How skills are found within repos
|
||||
Executable
+40
@@ -0,0 +1,40 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Doctrine check: every dir has index.md; index links every sibling file/dir."""
|
||||
import re, sys
|
||||
from pathlib import Path
|
||||
kb = Path(sys.argv[1])
|
||||
issues = []
|
||||
dirs = sorted({p.parent for p in kb.rglob("*.md")})
|
||||
for d in dirs:
|
||||
idx = d / "index.md"
|
||||
if not idx.is_file() and d != kb:
|
||||
issues.append(f"{d.relative_to(kb)}: no index.md")
|
||||
continue
|
||||
if not idx.is_file():
|
||||
continue
|
||||
text = idx.read_text(errors="replace")
|
||||
linked = set()
|
||||
for m in re.finditer(r"\]\((?!https?:|#)([^)#\s]+?)(?:#[^)]*)?\)", text):
|
||||
t = m.group(1)
|
||||
target = (d / t).resolve() if not t.startswith("/") else (kb / t.lstrip("/")).resolve()
|
||||
linked.add(target)
|
||||
# wikilinks too
|
||||
wl_names = {m.group(1).strip().rsplit("/", 1)[-1] for m in re.finditer(r"\[\[([^\]|#]+)", text)}
|
||||
for sib in sorted(d.iterdir()):
|
||||
if sib.suffix != ".md" or sib.name == "index.md":
|
||||
continue
|
||||
if sib.resolve() not in linked and sib.stem not in wl_names:
|
||||
issues.append(f"{d.relative_to(kb)}/index.md: does not link {sib.name}")
|
||||
# subdirs of d linked as their index?
|
||||
for sub in sorted(d.iterdir()):
|
||||
if sub.is_dir() and (sub / "index.md").is_file():
|
||||
subidx = (sub / "index.md").resolve()
|
||||
dirref = sub.resolve()
|
||||
if subidx not in linked and dirref not in linked:
|
||||
# also accept link to sub/ or sub/index.md or wikilink to dir name
|
||||
if not re.search(re.escape(sub.name) + r"[/)]", text):
|
||||
issues.append(f"{d.relative_to(kb)}/index.md: does not link subdir {sub.name}/")
|
||||
for i in issues:
|
||||
print(i)
|
||||
print(f"index-coverage: {len(issues)} issue(s)")
|
||||
sys.exit(1 if issues else 0)
|
||||
@@ -27,6 +27,16 @@ KBD="${KBD:-$HOME/.config/niri/cfg/keybinds.kdl}"
|
||||
[ -f "$KBD" ] || { echo "error: no such file: $KBD" >&2; exit 1; }
|
||||
|
||||
gen() {
|
||||
echo "---"
|
||||
echo "type: reference"
|
||||
echo "title: Niri Keybindings"
|
||||
echo "description: Live keybinding cheat sheet generated from $(basename "$KBD") — do not edit by hand."
|
||||
echo "tags:"
|
||||
echo " - niri"
|
||||
echo " - keybindings"
|
||||
echo "generated: { by: scripts/gen-keybinds.sh }"
|
||||
echo "---"
|
||||
echo
|
||||
echo "# Niri Keybindings"
|
||||
echo
|
||||
echo "> GENERATED by \`scripts/gen-keybinds.sh\` from \`$(basename "$KBD")\` — do not edit by hand."
|
||||
|
||||
+14
-3
@@ -7,6 +7,7 @@ KB="$(cd "${1:-omp-docs}" 2>/dev/null && pwd)" || { echo "kb-lint: no such dir:
|
||||
|
||||
python3 - "$KB" <<'PY'
|
||||
import re, sys
|
||||
import yaml
|
||||
from pathlib import Path
|
||||
kb = Path(sys.argv[1])
|
||||
violations = []
|
||||
@@ -14,6 +15,7 @@ violations = []
|
||||
for p in sorted(kb.rglob("*.md")):
|
||||
rel = p.relative_to(kb)
|
||||
text = p.read_text(errors="replace")
|
||||
lines = text.splitlines()
|
||||
if p.name == "index.md":
|
||||
# OKF rule: index files are directory listings and carry NO frontmatter.
|
||||
if text.startswith("---"):
|
||||
@@ -22,9 +24,18 @@ for p in sorted(kb.rglob("*.md")):
|
||||
if not text.startswith("---"):
|
||||
violations.append(f"{rel}: missing frontmatter")
|
||||
continue
|
||||
end = text.find("\n---", 3)
|
||||
fm = text[3:end] if end != -1 else ""
|
||||
if not re.search(r"^type:", fm, re.M):
|
||||
# Close the block at the first line that is exactly --- or ...; anything
|
||||
# else (including fenced `---` deep in the body) is body, not a delimiter.
|
||||
end = next((i for i in range(1, len(lines)) if lines[i].strip() in ("---", "...")), None)
|
||||
if end is None:
|
||||
violations.append(f"{rel}: frontmatter block is not closed (no '---' delimiter line)")
|
||||
continue
|
||||
try:
|
||||
fm = yaml.safe_load("\n".join(lines[1:end])) or {}
|
||||
except yaml.YAMLError:
|
||||
violations.append(f"{rel}: frontmatter block is malformed YAML or not closed")
|
||||
continue
|
||||
if not isinstance(fm, dict) or not str(fm.get("type", "")).strip():
|
||||
violations.append(f"{rel}: frontmatter lacks required 'type:'")
|
||||
|
||||
# link integrity: fenced code blocks hold example paths, not live links — strip first.
|
||||
|
||||
@@ -63,6 +63,13 @@ teardown() {
|
||||
grep -q 'GENERATED' "$TMP/out/keybindings.md"
|
||||
}
|
||||
|
||||
@test "output begins with OKF frontmatter so the artifact passes kb-lint" {
|
||||
run "$GEN" "$TMP/keybinds.kdl"
|
||||
[ "${lines[0]}" = '---' ]
|
||||
[[ "${lines[1]}" == 'type: reference' ]]
|
||||
grep -q '^generated:' <<<"$output"
|
||||
}
|
||||
|
||||
@test "missing input file fails loudly" {
|
||||
run "$GEN" "$TMP/nope.kdl"
|
||||
[ "$status" -ne 0 ]
|
||||
|
||||
Executable
+92
@@ -0,0 +1,92 @@
|
||||
#!/usr/bin/env bats
|
||||
# tests/kb-lint.bats — black-box tests for scripts/kb-lint.sh
|
||||
#
|
||||
# Contract: exit 0 when a knowledge bundle is OKF v0.1 conformant;
|
||||
# one line per violation otherwise. Observable surface: stdout lines
|
||||
# and exit status only.
|
||||
|
||||
setup() {
|
||||
LINT="$BATS_TEST_DIRNAME/../scripts/kb-lint.sh"
|
||||
KB="$(mktemp -d)/kb"
|
||||
mkdir -p "$KB/sub"
|
||||
cat > "$KB/index.md" <<'EOF'
|
||||
# Index
|
||||
|
||||
* [Good](good.md) — fine.
|
||||
EOF
|
||||
cat > "$KB/good.md" <<'EOF'
|
||||
---
|
||||
type: reference
|
||||
title: Good
|
||||
---
|
||||
Body.
|
||||
EOF
|
||||
}
|
||||
|
||||
teardown() { rm -rf "$(dirname "$KB")"; }
|
||||
|
||||
@test "conformant bundle passes" {
|
||||
run bash "$LINT" "$KB"
|
||||
[ "$status" -eq 0 ]
|
||||
}
|
||||
|
||||
@test "missing frontmatter is reported" {
|
||||
printf 'no frontmatter here\n' > "$KB/bad.md"
|
||||
run bash "$LINT" "$KB"
|
||||
[ "$status" -ne 0 ]
|
||||
[[ "$output" == *"bad.md: missing frontmatter"* ]]
|
||||
}
|
||||
|
||||
@test "frontmatter without type is reported" {
|
||||
printf -- '---\ntitle: x\n---\nbody\n' > "$KB/notype.md"
|
||||
run bash "$LINT" "$KB"
|
||||
[ "$status" -ne 0 ]
|
||||
[[ "$output" == *"notype.md"*"type"* ]]
|
||||
}
|
||||
|
||||
@test "unclosed frontmatter is reported, not silently passed" {
|
||||
# regression: a `---` in the body (fenced code, rule) must not be
|
||||
# accepted as the closing delimiter of the frontmatter block
|
||||
cat > "$KB/unclosed.md" <<'EOF'
|
||||
---
|
||||
type: reference
|
||||
title: Unclosed
|
||||
|
||||
# Heading after a forgotten closing fence
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: example
|
||||
---
|
||||
```
|
||||
EOF
|
||||
run bash "$LINT" "$KB"
|
||||
[ "$status" -ne 0 ]
|
||||
[[ "$output" == *"unclosed.md"* ]]
|
||||
}
|
||||
|
||||
@test "frontmatter in index.md is reported" {
|
||||
printf -- '---\ntype: x\n---\n# I\n' > "$KB/sub/index.md"
|
||||
run bash "$LINT" "$KB"
|
||||
[ "$status" -ne 0 ]
|
||||
[[ "$output" == *"index.md must not have frontmatter"* ]]
|
||||
}
|
||||
|
||||
@test "broken relative link is reported" {
|
||||
printf -- '---\ntype: reference\n---\nsee [x](gone.md)\n' > "$KB/links.md"
|
||||
run bash "$LINT" "$KB"
|
||||
[ "$status" -ne 0 ]
|
||||
[[ "$output" == *"links.md: broken relative link"* ]]
|
||||
}
|
||||
|
||||
@test "broken wikilink is reported" {
|
||||
printf -- '---\ntype: reference\n---\nsee [[nowhere]]\n' > "$KB/wiki.md"
|
||||
run bash "$LINT" "$KB"
|
||||
[ "$status" -ne 0 ]
|
||||
[[ "$output" == *"wiki.md: broken wikilink"* ]]
|
||||
}
|
||||
|
||||
@test "missing kb directory exits 2" {
|
||||
run bash "$LINT" "$KB/no-such-dir"
|
||||
[ "$status" -eq 2 ]
|
||||
}
|
||||
Reference in New Issue
Block a user