dank/command-center
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rebuild KB in OKF v0.1 with live-verified facts

Browse Source 
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center
knowledge base: concept files promoted to path identity, index listings
stripped of frontmatter, all wikilinks/relative links resolved, every
checkable claim verified against the live fleet (Dankserver = Ryzen 7
7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged.
kb-lint exits 0.
This commit is contained in:
Frank
2026-08-28 07:57:13 -07:00
parent 552d1ef8bf
commit 02883d3ed2
116 changed files with 13008 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
omp-docs/engineering/agents-files.md
+100
View File
@@ -0,0 +1,100 @@
---
type: reference
title: Agent Instruction Files and Agent Skills
description: Best practices for AGENTS.md, CLAUDE.md, SYSTEM.md, and the Agent Skills SKILL.md standard.
tags:
- agents-md
- claude-md
- system-md
- agent-skills
- unverified
timestamp: 2026-08-11
---
verified: 2026-08-28
# Agent Instruction Files and Agent Skills
This page explains the files that control how an AI coding agent works in a project. Use it when you create or review agent behavior configuration.
## AGENTS.md
`AGENTS.md` is the open, cross-tool format for coding-agent instructions. The Agentic AI Foundation (under the Linux Foundation) stewards it. Over 20 coding agents support it, including Cursor, Codex, and Claude Code.
The format is plain Markdown. It has no required fields. Any heading structure works. Agents read the nearest `AGENTS.md` in the directory tree. In a monorepo, the agent uses a nested `AGENTS.md` per package.
Include these sections in an `AGENTS.md`:
* Project overview.
* Setup and build commands.
* Code style guidelines.
* Testing instructions.
* Pull request instructions.
* Security considerations.
* Deployment steps.
* Commit message conventions.
Agents load content progressively. Put a short summary at the top. Put detailed instructions in later sections.
## CLAUDE.md
`CLAUDE.md` is Anthropic's tool-specific instruction file. Claude Code reads `CLAUDE.md` by default, not `AGENTS.md`. Files load in this order:
1. Managed policy (`/etc/claude-code/CLAUDE.md`).
2. User scope (`~/.claude/CLAUDE.md`).
3. Project scope (`./CLAUDE.md`).
4. Local scope (`./CLAUDE.local.md`).
Keep each file under 200 lines. Use the `@path/to/file` syntax to import other files. Use path-scoped rules in `.claude/rules/*.md` with `paths` frontmatter for directory-specific rules.
To make a repository work in both AGENTS.md and CLAUDE.md workflows, create a `CLAUDE.md` that imports `AGENTS.md` with the `@AGENTS.md` syntax, or use a symlink.
## SYSTEM.md
`SYSTEM.md` sets the system-level role and behavior for an agent. It establishes the persona, the prime directive, and the binding rules. In this setup, `/home/dank/.pi/agent/SYSTEM.md` defines the Comrade Chief Designer persona and the ASD-STE100 voice rules.
Use `SYSTEM.md` for stable, cross-project rules. Use `AGENTS.md` for project-specific context. Do not duplicate content between them. Keep the division of labor clear.
## Agent Skills Standard
An agent skill is a directory that contains a `SKILL.md` file. Skills extend an agent's capabilities. The open standard lives at [agentskills.io](https://agentskills.io). Over 50 agents support it.
The `SKILL.md` frontmatter includes these fields:
```yaml
---
name: my-skill
description: What this skill does
license: MIT
compatibility: node>=18
metadata:
internal: false
---
```
The `name` field is required and must use lowercase alphanumeric plus hyphens. The `description` field is required. Keep the name under 64 characters. Keep the description under 1024 characters.
Skills use progressive disclosure in three stages:
* Discovery: the agent loads only the name and description at startup.
* Activation: the agent reads the full `SKILL.md` when a task matches.
* Execution: the agent follows the instructions and reads resources on demand.
This keeps the context footprint small.
## Distribution
Distribute skills through npm packages with a `pi` manifest, or through the `skills` CLI from Vercel Labs. See the [Skills Documentation](../skills/index.md) pages for details.
## Citations
* [agents.md](https://agents.md/)
* [OpenAI Agentic AI Foundation](https://openai.com/index/agentic-ai-foundation/) (unverified — returned 403)
* [Claude Code memory documentation](https://code.claude.com/docs/en/memory)
* [Agent Skills standard](https://agentskills.io/)
* [agentskills/agentskills](https://github.com/agentskills/agentskills)
* [vercel-labs/skills](https://github.com/vercel-labs/skills)
## See Also
* [SDLC and Tooling](sdlc.md)
* [Skills Ecosystem](skills-ecosystem.md)
omp-docs/engineering/index.md
+26
View File
@@ -0,0 +1,26 @@
# Software Engineering Best Practices
Current (2025/2026) best practices for software projects, grouped by lifecycle and ecosystem.
This area distills grounded research into an OKF knowledge bundle. Each page covers one domain. Cross-links connect related pages.
## Topics
* [SDLC and Tooling](sdlc.md) - Git branching, CI/CD, testing, code review, versioning, dev environments.
* [Agent Instruction Files](agents-files.md) - AGENTS.md, CLAUDE.md, SYSTEM.md, and the Agent Skills standard.
* [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.
* [Signal Remote Control](signal-remote.md) - Drive a pi instance from Signal messages.
## Conventions
Sources appear in each page under `# Citations`. Timestamps use ISO 8601. The bundle follows the [OKF v0.1 specification](../references/okf-spec.md).
## See Also
* [Research](../research/index.md) - Hardware-specific research.
* [Agentic Web Research](../agentic-web-research/index.md) - Self-hosted web research infrastructure.
* [Pi Configuration](../pi/index.md) - The local pi agent setup.
* [Skills Documentation](../skills/index.md) - Skill distribution and installation patterns.
omp-docs/engineering/infra/cloud.md
+80
View File
@@ -0,0 +1,80 @@
---
type: reference
title: Cloud Providers - AWS, DigitalOcean, Hetzner
description: Current best practices for AWS, DigitalOcean, and Hetzner - bootstrapping, IaC, cost, and lifecycle.
tags:
- aws
- digitalocean
- hetzner
- cloud
- infrastructure
- engineering
timestamp: 2026-08-11
verified: 2026-08-28
---
# Cloud Providers
This page compares current (2025/2026) practices for AWS, DigitalOcean, and Hetzner.
## AWS
Use infrastructure as code with Terraform or OpenTofu. Build a landing zone with AWS Control Tower or a `aws-landing-zone` module.
Use these services as the baseline:
* EC2 for compute.
* RDS for managed databases.
* EKS for managed Kubernetes.
* VPC for networking.
* S3 for object storage.
* IAM for access control.
Optimize cost with Savings Plans, Spot instances for stateless work, and Reserved instances for databases.
Set a security baseline with organization SCPs, GuardDuty, Security Hub, and KMS for encryption.
## DigitalOcean
Use Droplets for simple virtual servers. Use the App Platform as a PaaS for containerized applications. Use managed databases for PostgreSQL, MySQL, and Redis.
Use `doctl` as the command-line tool. Use the Terraform provider for infrastructure as code.
Droplets start around $4 per month. DigitalOcean costs more per compute unit than Hetzner but gives a better developer experience.
## Hetzner
Hetzner Cloud offers a strong cost advantage. Compute costs are roughly half or less than DigitalOcean and AWS.
Use the `hcloud` CLI or the official `hashicorp/hcloud` Terraform provider. Manage servers, networks, firewalls, load balancers, and volumes.
Hetzner has fewer regions. It has no managed Kubernetes service and no managed databases. Run k3s, k0s, or Talos for Kubernetes.
Hetzner suits cost-sensitive homelabs, European workloads, and k3s or k0s clusters.
## Provider Decision
| Factor | AWS | DigitalOcean | Hetzner |
|--------|-----|--------------|---------|
| Cost | High | Medium | Low |
| Services | Enterprise | Managed databases | Limited |
| Regions | Many | Several | Few |
| Best for | Enterprise | Developer experience | Cost-sensitive clusters |
## Related Tools
* cloud-init for first-boot configuration.
* Ansible for configuration management.
* WireGuard or Tailscale for private networking.
* Cloudflare Tunnels to expose services without open ports.
## Citations
* [AWS documentation](https://docs.aws.amazon.com/)
* [DigitalOcean](https://www.digitalocean.com/)
* [Hetzner Cloud](https://www.hetzner.com/cloud/)
* [Terraform hcloud provider](https://registry.terraform.io/providers/hetznercloud/hcloud/latest/docs)
## See Also
* [Terraform and OpenTofu](terraform.md)
* [Kubernetes](kubernetes.md)
omp-docs/engineering/infra/containers.md
+100
View File
@@ -0,0 +1,100 @@
---
type: reference
title: Docker and Podman
description: Current best practices for Docker and Podman - BuildKit, multi-stage builds, rootless operation, and pods.
tags:
- docker
- podman
- containers
- infrastructure
- engineering
timestamp: 2026-08-16
verified: 2026-08-28
---
# Docker and Podman
This page covers current (2025/2026) best practices for containers.
## Docker
Use BuildKit for builds. It enables incremental builds, cache mounts, and secret mounts.
Use multi-stage builds for production images. Build in a full stage with the toolchain. Copy only the artifacts to a minimal final stage. Name each stage with `AS`.
Harden images with these practices:
* Use distroless or alpine base images.
* Set `USER` to a non-root user.
* Use `ENTRYPOINT` in exec form.
* Add a `HEALTHCHECK`.
* Pin base image digests.
* Use a `.dockerignore` file.
Use Docker Compose v2 for multi-container applications. Run `docker compose` without a hyphen.
## Podman
Podman runs without a daemon and rootless by default. Run it as a non-root user. An alias `alias docker=podman` works for most commands.
Use Podman pods to group containers that share network and IPC namespaces. Pods suit single-host service groups.
Use Quadlet for container lifecycle management under systemd. `podman generate systemd` is deprecated as of Podman 5.7; the deprecation notice points to Quadlet.
Podman is a good choice for Linux servers, homelabs, and CI runners.
### Quadlet (systemd-managed containers)
Quadlet files are systemd unit files with a podman section (`[Container]`, `[Network]`, etc.). Podman ships a systemd generator that turns them into `container` services.
Rootless search path: `~/.config/containers/systemd/`. System-wide: `/etc/containers/systemd/`.
| Fact | Value |
|------|-------|
| Unit naming (podman 5.x) | `foo.container` → `foo.service` (no `container-` prefix) |
| Container naming | `ContainerName=foo` or default `systemd-foo` |
| Boot start | `[Install] WantedBy=default.target` in the file; the generator applies it |
| Rootless boot start | enable user-level linger: `loginctl enable-linger <user>` |
| Start behavior | `podman run --name ... --replace --rm`; stop removes the container |
| Cross-container deps | `[Unit] Wants=` / `After=` referencing other quadlet unit names |
| Network | `Network=foo.network` uses a podman network created from `foo.network` |
| Long pulls | add `[Service] TimeoutStartSec=900` |
Reference: `man podman-systemd.unit` (podman-systemd.unit(5)).
#### Gotchas found in the field (2026-08-16, Gitea migration on dankclaw)
- The automatic rootless default network (`podman`) has `dns_enabled: false`. Container names do not resolve on it. Create a quadlet `.network` file (DNS is enabled by default for quadlet networks) and point the containers at it.
- `${VAR}` expansion in the generated `ExecStart` needs the variable in the *systemd unit environment*. Put `EnvironmentFile=/path/to/env` in the `[Service]` section of the quadlet file. An `EnvironmentFile=` in `[Container]` only lands in the ignored `[X-Container]` section and does not feed expansion.
- A podman restart (or `systemctl --user daemon-reload`) re-runs the generator after quadlet file edits. Verify the parsed unit with `systemctl --user cat <unit>`.
- Bind-mounted files created by the container are owned by the mapped host UID (container uid 1000 → first subuid + 1000). Edit them with `podman exec --user 1000 <container> ...`.
#### Gotchas found in the field (2026-08-19, SearXNG trio migration on dankclaw)
- The quadlet generator rejects several compose-familiar keys in `[Container]` and **silently skips the whole unit** (the error is only in `journalctl --user`, and the unit simply never appears in `systemctl list-unit-files`). Use the podman-flag names: `AddCapability=` (not `CapAdd=`), `AddDevice=HOST:CONTAINER` (not `Device=` — that is a `[Volume]` key). When a unit mysteriously does not generate, read the journal for `quadlet-generator: converting "...": unsupported key`.
- Quadlet units are **generated** units (they live in `/run/user/UID/systemd/generator/`). `systemctl enable <unit>` fails on them with "transient or generated". You do not enable them: the `[Install] WantedBy=default.target` in the `.container` file *is* the enablement — `systemctl is-enabled` reports `generated`. With user linger on, they start at boot. Just `daemon-reload` then `start`.
- A `.network` unit is also generated and cannot be enabled. It is pulled in automatically by any container that sets `Wants=`/`After=` on it (or `Network=<name>.network`).
- To make one container reuse another's network namespace (the compose `network_mode: service:X` equivalent), set `Network=<name>.container` on the consumer. The generator adds the dependency on `<name>.service`. This is how SearXNG exits the Gluetun WireGuard tunnel: `Network=gluetun.container`.
- Pin a quadlet network CIDR with `Subnet=<cidr>` in the `.network` file (maps to `podman network create --subnet`). Rootless podman otherwise reassigns the CIDR, which breaks any `trusted_proxies` entry that references it.
- A working pattern for a boot-persistent trio: a `.network` (DNS on, `Subnet=` pinned) that the VPN client and the cache join, plus the consumer container on `Network=<vpn>.container`. Secrets live in a mode-0600 env file referenced by `EnvironmentFile=` in each unit's `[Service]`.
## Docker vs Podman
| Factor | Docker | Podman |
|--------|--------|--------|
| Platform | Mac and Windows | Linux focus |
| Model | Daemon-based | Rootless and daemonless |
| Default user | Root | Non-root |
| Grouping | Compose services | Pods |
Use Docker for cross-platform development. Use Podman rootless for Linux servers and security-conscious deployments.
## Citations
* [Docker documentation](https://docs.docker.com/)
* [Podman documentation](https://podman.io/docs)
* [Container Specification](https://containers.dev/)
## See Also
* [Kubernetes](kubernetes.md)
* [Go](../languages/go.md)
omp-docs/engineering/infra/index.md
+15
View File
@@ -0,0 +1,15 @@
# Infrastructure and Cloud
Current (2025/2026) best practices for infrastructure as code, containers, orchestration, and cloud providers.
## Topics
* [Terraform and OpenTofu](terraform.md) - IaC modules, state, backends, and orchestration.
* [Docker and Podman](containers.md) - BuildKit, multi-stage builds, rootless, and pods.
* [Kubernetes](kubernetes.md) - Helm, k3s, k0s, and Talos.
* [Cloud Providers](cloud.md) - AWS, DigitalOcean, and Hetzner.
## See Also
* [Engineering](../index.md) - The parent area.
* [SDLC and Tooling](../sdlc.md)
omp-docs/engineering/infra/kubernetes.md
+80
View File
@@ -0,0 +1,80 @@
---
type: reference
title: Kubernetes
description: Current best practices for Kubernetes - Helm charts, k3s, k0s, and Talos Linux.
tags:
- kubernetes
- helm
- k3s
- k0s
- talos
- infrastructure
- engineering
timestamp: 2026-08-11
verified: 2026-08-28
---
# Kubernetes
This page covers current (2025/2026) best practices for Kubernetes.
## Helm
Use Helm to manage charts. Follow the canonical chart layout:
```
my-chart/
├── Chart.yaml
├── values.yaml
├── values.schema.json
├── charts/
├── templates/
│ ├── deployment.yaml
│ ├── service.yaml
│ └── _helpers.tpl
├── .helmignore
└── NOTES.txt
```
Use `_helpers.tpl` for consistent labels, such as `app.kubernetes.io/*`. Separate `values.yaml` per environment. Pin chart versions in CI. Run `helm lint` before packaging.
Set `securityContext` to non-root and read-only root filesystem. Set resource requests and limits.
## Distribution Choices
| Tool | Best For | Notes |
|------|----------|-------|
| k3s | Fast bootstrap | Single binary, embedded addons, quick setup. |
| k0s | Vanilla Kubernetes | No host dependencies, `k0sctl` lifecycle tool. |
| Talos Linux | Secure immutable clusters | Small footprint, API-driven config. |
### k3s
Install with:
```bash
curl -sfL https://get.k3s.io | sh -
```
k3s is a single binary under 100 MB. It is ready in about 30 seconds. Use SQLite for single-node or embedded etcd for high availability.
### Talos Linux
Talos is an immutable Kubernetes OS. It has no SSH, no shell, and no package manager. Configure it with declarative YAML through the `talosctl` gRPC API. Use automatic A/B upgrades with rollback.
## Related Tools
* Cilium or Calico for networking.
* ArgoCD or Flux for GitOps deployment.
* k0sctl for cluster lifecycle.
## Citations
* [Helm](https://helm.sh/)
* [k3s](https://k3s.io/)
* [k0s](https://k0sproject.io/)
* [Talos Linux](https://www.talos.dev/)
## See Also
* [Docker and Podman](containers.md)
* [Cloud Providers](cloud.md)
omp-docs/engineering/infra/terraform.md
+79
View File
@@ -0,0 +1,79 @@
---
type: reference
title: Terraform and OpenTofu
description: Current best practices for Terraform and OpenTofu - module structure, state management, backends, and orchestration.
tags:
- terraform
- opentofu
- iac
- infrastructure
- engineering
timestamp: 2026-08-11
verified: 2026-08-28
---
# Terraform and OpenTofu
This page covers current (2025/2026) best practices for Terraform and OpenTofu.
## OpenTofu vs Terraform
OpenTofu is the open-source fork of Terraform. It uses the MPL 2.0 license. Terraform moved to the Business Source License. Both remain compatible with the same configurations and most providers.
Use OpenTofu when license portability matters. Use Terraform when you need HashiCorp's commercial extensions.
## Module Structure
Separate infrastructure into layers:
```
infrastructure/
├── modules/ # Reusable building blocks
└── environments/
├── dev/
├── stage/
└── prod/
```
Environment modules call the reusable modules. Root modules declare providers and the backend.
## State Management
Never commit `.tfstate` to version control. Use a remote backend only.
The AWS remote backend uses S3 and DynamoDB:
* `bucket` for the state bucket.
* `key` for the state file path.
* `dynamodb_table` for state locking.
* `encrypt` for encryption at rest.
Enable versioning and server-side encryption on the state bucket.
Use separate state files per environment. Do not use workspaces for separate environments.
## Security and Lifecycle
* Mark sensitive values with `sensitive = true`.
* Pin provider versions with `required_providers`.
* Run `terraform import` to adopt existing infrastructure.
* Run `terraform plan` periodically to detect drift.
* Use lifecycle blocks for resource replacement policies.
## Related Tools
* Terragrunt for orchestration: DRY config, hooks, and run queues.
* Pulumi for infrastructure as code in real programming languages.
* Packer for building machine images.
* Atlantis for pull request based Terraform CI/CD.
## Citations
* [Terraform documentation](https://developer.hashicorp.com/terraform)
* [OpenTofu](https://opentofu.org/)
* [Terragrunt](https://terragrunt.com/)
* [AWS backend](https://developer.hashicorp.com/terraform/language/settings/backends/s3)
## See Also
* [Cloud Providers](cloud.md)
* [Kubernetes](kubernetes.md)
omp-docs/engineering/languages/go.md
+93
View File
@@ -0,0 +1,93 @@
---
type: reference
title: Go
description: Current best practices for Go projects - modules, project layout, HTTP frameworks, and tooling.
tags:
- go
- golang
- bootstrap
- engineering
timestamp: 2026-08-11
verified: 2026-08-28
---
CUT
# Go
This page covers current (2025/2026) best practices for Go projects.
## Bootstrap
Initialize a module:
```bash
go mod init my-module
```
Then write a `main.go` with `package main`.
## Project Layout
Follow the Standard Go Project Layout:
```
my-project/
├── cmd/ # Application entrypoints
├── internal/ # Private application code
├── pkg/ # Public library code
├── api/ # Protobuf or OpenAPI definitions
├── deploy/ # Dockerfiles and Helm charts
├── scripts/ # Build and CI scripts
├── go.mod
└── go.sum
```
Use `internal/` for code that must stay private to the module.
## Tooling
| Category | Tool | Notes |
|----------|------|-------|
| Module manager | go modules | Built into the toolchain. |
| Formatter | gofmt | Built in. |
| Linter | golangci-lint | The standard CI aggregator. |
| Testing | `go test ./...` | Use table-driven tests. |
| Static analysis | staticcheck | Use with golangci-lint. |
## HTTP Frameworks
| Framework | Best For | Notes |
|-----------|----------|-------|
| Standard `net/http` | Most Go projects | Idiomatic, no dependencies. |
| chi v5 | REST APIs | Minimalist, stdlib-compatible. |
| gin | High-throughput APIs | Fast, JSON binding. |
| echo | Full-featured APIs | Middleware and validation. |
Use the standard library or chi for most projects.
## Notable 2025/2026 Changes
* Go 1.24 added generic type aliases and `tool` directives in `go.mod`.
* `go run` and `go build` cache executables and embed VCS metadata.
* `go test -json` gives structured output for CI.
## Related Technologies
* pgx for PostgreSQL.
* slog for structured logging.
* cobra for command-line interfaces.
* gRPC with `google.golang.org/grpc`.
* testcontainers-go for integration tests.
## Citations
* [Go modules](https://go.dev/doc/modules)
* [Go 1.24 release notes](https://go.dev/doc/go1.24)
* [Standard Go Project Layout](https://github.com/golang-standards/project-layout)
* [chi](https://github.com/go-chi/chi)
## See Also
* [SDLC and Tooling](../sdlc.md)
* [Rust](rust.md)
* [Docker and Podman](../infra/containers.md)
omp-docs/engineering/languages/index.md
+22
View File
@@ -0,0 +1,22 @@
# Language and Framework Stacks
Current (2025/2026) bootstrap, tooling, and best practices for the major language ecosystems.
Each page covers one ecosystem. Use the page that matches the project language.
## Topics
* [Node.js and JavaScript](node-js.md) - Runtimes, package managers, TypeScript, tooling, monorepos.
* [React](react.md) - Vite vs Next.js, component patterns, testing.
* [Python](python.md) - uv, pyproject.toml, frameworks, linting, testing.
* [Rust](rust.md) - cargo, editions, web frameworks, tooling.
* [Go](go.md) - modules, project layout, HTTP frameworks, tooling.
## Cross-Ecosystem Patterns
* [SDLC and Tooling](../sdlc.md) - Git, CI/CD, testing, environments.
* [Infrastructure and Cloud](../infra/index.md) - Containers and deployment.
## See Also
* [Engineering](../index.md) - The parent area.
omp-docs/engineering/languages/node-js.md
+87
View File
@@ -0,0 +1,87 @@
---
type: reference
title: Node.js and JavaScript
description: Current bootstrap, tooling, and framework best practices for Node.js and JavaScript projects.
tags:
- node
- javascript
- typescript
- bootstrap
- engineering
timestamp: 2026-08-11
verified: 2026-08-28
---
CUT
# Node.js and JavaScript
This page covers current (2025/2026) best practices for Node.js and JavaScript projects.
## Runtime and Package Manager
Use Node.js 22 LTS or Node.js 24 LTS. Use these versions for stability in production.
Choose a package manager by project type:
* npm for the default.
* pnpm for monorepos.
* Bun as an all-in-one runtime, package manager, test runner, and bundler.
## TypeScript
TypeScript is the default for new projects. Configure `strict: true` in `tsconfig.json`. Target `ES2022` or later. Use `module: ESNext` and `moduleResolution: bundler`.
## Bootstrap
Scaffold a Vite project with:
```bash
npm create vite@latest my-app -- --template react-ts
```
Scaffold a full-stack SSR app with Next.js:
```bash
npx create-next-app@latest my-app --yes
```
## Tooling
| Category | Tool | Notes |
|----------|------|-------|
| Linter | ESLint 9 with flat config | Use `eslint.config.mjs`. |
| Formatter | Prettier or Biome | Biome is faster and Prettier-compatible. |
| Testing | Vitest or Jest | Vitest is the default for Vite projects. |
| Bundler | Vite or Turbopack | Turbopack is the Next.js default. |
Use Biome if you want one fast tool for lint and format. Biome gained many lint rules from ESLint and TypeScript ESLint.
## Frameworks
* Express and Fastify for minimal servers.
* NestJS for structured, opinionated applications.
* Next.js for full-stack React with server-side rendering.
## Monorepos
Use Turborepo or Nx for JavaScript and TypeScript monorepos. Combine these tools with pnpm workspaces for dependency management.
## Related Technologies
* Remix, Nuxt, Astro, and SvelteKit as other meta-frameworks.
* Deno as an alternative runtime.
* esm.sh as a CDN for npm packages as ES modules.
## Citations
* [Node.js releases](https://nodejs.org/en/about/releases)
* [Vite](https://vite.dev/)
* [Biome](https://biomejs.dev/)
* [Vitest](https://vitest.dev/)
* [Bun](https://bun.com/)
* [Next.js documentation](https://nextjs.org/docs)
## See Also
* [React](react.md)
* [SDLC and Tooling](../sdlc.md)
omp-docs/engineering/languages/python.md
+79
View File
@@ -0,0 +1,79 @@
---
type: reference
title: Python
description: Current best practices for Python projects - uv, pyproject.toml, frameworks, linting, and testing.
tags:
- python
- uv
- fastapi
- django
- bootstrap
- engineering
timestamp: 2026-08-11
verified: 2026-08-28
---
CUT
# Python
This page covers current (2025/2026) best practices for Python projects.
## Package and Project Management
Use `uv` for new projects. `uv` replaces pip, pip-tools, pyenv, poetry, and virtualenv. It is much faster than pip and supports workspaces and lockfiles.
Scaffold a project with:
```bash
uv init my-project --bare
```
The command creates a `pyproject.toml` and a virtual environment. A `uv.lock` file pins exact dependency versions. Do not edit the lockfile by hand.
Use `pyproject.toml` as the project manifest. It follows PEP 621. This replaces the older `setup.py`.
## Tooling
| Category | Tool | Notes |
|----------|------|-------|
| Linter and formatter | Ruff | Replaces Black, isort, flake8, and pylint. |
| Type checker | pyright or mypy | Use pyright in VS Code. Use mypy for strict CI. |
| Testing | pytest | Use pytest-asyncio for async tests. |
| Pre-commit | pre-commit | Run ruff, mypy, and pytest. |
## Framework Comparison
| Framework | Best For | Notes |
|-----------|----------|-------|
| FastAPI | Modern REST APIs, async | Auto documentation, type-hint validation. |
| Django | Full-stack web apps | Batteries included: ORM, admin, auth. |
| Flask | Lightweight apps | Simpler than FastAPI. |
Use FastAPI for new REST APIs. The recommended workflow is `uv run fastapi dev`.
## Notable 2025/2026 Changes
* `uv` is the dominant project manager.
* `ruff` replaced most separate lint and format tools.
* `pyproject.toml` is the universal manifest.
* Python 3.12 gives stability. Python 3.13 adds performance improvements.
## Related Technologies
* Uvicorn as the ASGI server.
* SQLAlchemy 2.0 with Alembic for the ORM and migrations.
* httpx for async HTTP clients.
* pydantic-settings for configuration.
* OpenTelemetry for observability.
## Citations
* [uv documentation](https://docs.astral.sh/uv/)
* [Ruff](https://ruff.rs/)
* [FastAPI](https://fastapi.tiangolo.com/)
* [pyproject-build](https://pyproject-build.github.io/)
## See Also
* [SDLC and Tooling](../sdlc.md)
* [Infrastructure and Cloud](../infra/index.md)
omp-docs/engineering/languages/react.md
+82
View File
@@ -0,0 +1,82 @@
---
type: reference
title: React
description: Current best practices for React - Vite vs Next.js, component patterns, and testing.
tags:
- react
- nextjs
- frontend
- bootstrap
- engineering
timestamp: 2026-08-11
verified: 2026-08-28
---
CUT
# React
This page covers current (2025/2026) best practices for React projects.
## Framework Choice
Create React App is deprecated. Use Vite or Next.js for new projects.
* Use Vite + React for a single-page application with a separate API.
* Use Next.js for a full-stack application with server-side rendering.
Next.js uses the App Router with React Server Components by default. Components render on the server unless you mark them with `"use client"`.
## Bootstrap
Scaffold a Vite project:
```bash
npm create vite@latest my-app -- --template react-ts
```
Scaffold a Next.js project:
```bash
npx create-next-app@latest my-app --yes
```
## Tooling
| Category | Tool | Notes |
|----------|------|-------|
| CSS | Tailwind CSS | Default in create-next-app. |
| State | Zustand and TanStack Query | Zustand for client state. TanStack Query for server state. |
| Testing | Vitest and Testing Library | Unit and integration tests. |
| End-to-end | Playwright or Cypress | For user journeys. |
| Lint and format | Biome or ESLint | Use Biome for one fast tool. |
## Component Patterns
* Keep components, hooks, and types near the routes that use them.
* Use route groups for organization without changing the URL.
* Use `_components` for code that must not become a route.
* Use React Server Components to reduce client-side state.
## Notable 2025/2026 Changes
* React 19 is stable with Actions and new hooks.
* Next.js 16 uses Turbopack as the default bundler.
* Next.js no longer runs the linter as part of `next build`.
## Related Technologies
* Remix, Redwood, Gatsby, and Astro as other meta-frameworks.
* Playwright for end-to-end testing.
* Vercel Edge Functions and Cloudflare Workers for serverless.
## Citations
* [React](https://react.dev/)
* [Next.js project structure](https://nextjs.org/docs/app/getting-started/project-structure)
* [Biome](https://biomejs.dev/)
* [Vitest](https://vitest.dev/)
## See Also
* [Node.js and JavaScript](node-js.md)
* [Agent Instruction Files](../agents-files.md)
omp-docs/engineering/languages/rust.md
+97
View File
@@ -0,0 +1,97 @@
---
type: reference
title: Rust
description: Current best practices for Rust projects - cargo, editions, web frameworks, and tooling.
tags:
- rust
- cargo
- axum
- bootstrap
- engineering
timestamp: 2026-08-11
verified: 2026-08-28
---
CUT
# Rust
This page covers current (2025/2026) best practices for Rust projects.
## Bootstrap
Create a binary crate:
```bash
cargo new my-app --bin
```
Create a library crate:
```bash
cargo new my-lib --lib
```
New projects use the Rust 2024 edition by default.
## Tooling
| Category | Tool | Notes |
|----------|------|-------|
| Toolchain | rustup | Install with the rustup script. |
| Formatter | rustfmt | Run `cargo fmt`. |
| Linter | clippy | Run `cargo clippy --all-targets --all-features`. |
| Testing | `cargo test` | Unit tests in `#[cfg(test)]`, integration tests in `tests/`. |
| Async runtime | tokio | The standard choice. |
Use `cargo clippy -- -D warnings` in CI.
## Workspaces
Use a Cargo workspace for projects with multiple crates. Declare members in the root `Cargo.toml`.
```
workspace-root/
├── Cargo.toml
└── crates/
├── app/
└── core/
```
## Web Frameworks
| Framework | Best For | Notes |
|-----------|----------|-------|
| Axum 0.8 | Most Rust web apps | Most popular. Tokio team. |
| actix-web | High-throughput services | Slightly faster in benchmarks. |
| Rocket | Developer experience | Excellent ergonomics. |
Use Axum for new web services.
## Error Handling
Use `thiserror` for library error types. Use `anyhow` for application-level errors. The `?` operator propagates errors.
## Desktop and WASM
* Use Tauri 2 for cross-platform desktop apps with a web frontend.
* Use `wasm-pack` and `wasm-bindgen` for WebAssembly.
## Related Technologies
* serde and serde_json for serialization.
* clap for command-line interfaces.
* tracing and tracing-subscriber for structured logging.
* sqlx for compile-time checked SQL.
* tonic for gRPC.
* criterion for benchmarks.
## Citations
* [The Cargo Book](https://doc.rust-lang.org/cargo/)
* [Axum](https://docs.rs/axum/)
* [Tauri](https://v2.tauri.app/)
## See Also
* [SDLC and Tooling](../sdlc.md)
* [Go](go.md)
omp-docs/engineering/plugins.md
+53
View File
@@ -0,0 +1,53 @@
---
type: reference
title: Pi Plugins
description: The pi extension ecosystem and its notable packages - subagents, web access, permission, and skills.
tags:
- pi
- plugins
- packages
- engineering
timestamp: 2026-08-11
---
verified: 2026-08-28
# Pi Plugins
This page covers the pi coding agent extension ecosystem. Pi extends itself through npm packages installed with `pi install`. Each package provides extensions, skills, prompts, or themes.
## How Plugins Work
A pi plugin is an npm package that contains a `pi` manifest. The manifest points to the package's `skills/` and `extensions/` directories. The system reads the manifest at startup and loads the listed capabilities.
Plugins install to the pi home directory. Locally installed packages in this setup include `pi-peon`, `pi-web-access`, and the core `pi-subagents` extension. See the [Pi Packages](../pi/packages/index.md) page for local details.
## Notable Packages
The table lists packages verified in the npm registry during research. Popularity signals are approximate and change over time.
| Package | Purpose |
|---------|---------|
| `pi-subagents` | Core subagent delegation with chains and parallel execution. |
| `pi-web-access` | Web search, URL fetching, GitHub cloning, PDF extraction. |
| `@wierdbytes/pi-peon` | CESP/OpenPeon sound packs for lifecycle events. |
| `bigpowers` | A large collection of spec-driven development skills. |
| `pi-permission` | Layered shell command permissions. |
| `@anton-kochev/pi-skills` | Plan mode, TDD, and SRS skills (deprecated). |
Some package names that appear in older documentation, such as `pi-browser-use` and `pi-permission-system`, did not resolve in the npm registry at research time. Verify a package name before you install it.
## 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.
## Citations
* [npm registry](https://www.npmjs.com/)
* [Agent Skills standard](https://agentskills.io/)
* [vercel-labs/skills](https://github.com/vercel-labs/skills)
## See Also
* [Pi Configuration](../pi/index.md)
* [Pi Packages](../pi/packages/index.md)
* [Skills Documentation](../skills/index.md)
omp-docs/engineering/sdlc.md
+115
View File
@@ -0,0 +1,115 @@
---
type: reference
title: SDLC and Tooling Best Practices
description: Current best practices for the software development life cycle - git, CI/CD, testing, review, versioning, and dev environments.
tags:
- sdlc
- git
- ci-cd
- testing
- tooling
- unverified
timestamp: 2026-08-11
---
verified: 2026-08-28
# SDLC and Tooling Best Practices
This page distills current (2025/2026) best practices for running a software project. Use it when you bootstrap a new repository or when you review an existing one.
## Git Branching
Trunk-based development dominates. Teams use short-lived feature branches and merge into a single shared `main` branch. Feature flags hide incomplete features. This replaces older models such as GitFlow for most projects.
Use GitHub Flow as the default for new projects. Create a branch for each change. Open a pull request for every change. Merge the change after review. Deploy from `main` at any time.
The rule `main` must stay deployable at all times.
## Continuous Integration and Delivery
GitHub Actions is the most common CI/CD platform. Workflows live in `.github/workflows/`. A standard workflow follows this order: lint, test, build, deploy.
Use these patterns:
* Run one pipeline for pull request checks.
* Run a separate pipeline for `main` branch deployments.
* Use matrix builds to test multiple tool versions.
* Cache dependencies between runs.
* Split shared steps into reusable workflows.
## Testing
Follow the testing pyramid. Write many unit tests. Write fewer integration tests. Write the fewest end-to-end tests.
| Layer | Speed | Focus |
|-------|-------|-------|
| Unit | Fast | Isolated functions and modules |
| Integration | Medium | Service-to-service interaction |
| End-to-end | Slow | Complete user journeys |
Aim for roughly ten unit tests per integration test, and ten integration tests per end-to-end test.
## Code Review
Reduce review friction with these tools:
* Pull request templates for consistency.
* `CODEOWNERS` to assign reviewers by path.
* Required review before merge.
* Pre-commit hooks for lint and format checks.
## Semantic Versioning
Version numbers follow the `MAJOR.MINOR.PATCH` format.
* MAJOR changes when an API breaks compatibility.
* MINOR changes when features stay compatible.
* PATCH changes fix bugs in a compatible way.
Pre-release versions use `-alpha`, `-beta`, or `-rc` suffixes.
## Development Environments
Use `mise` to manage tool versions, environment variables, and named tasks in one `mise.toml` file. `mise` replaces the separate tools asdf and direnv, and it replaces a `Makefile` for tasks.
Use Dev Containers for reproducible environments. The Dev Container Specification uses `.devcontainer/devcontainer.json`. It works with VS Code, Codespaces, and the container CLI.
## Per-Ecosystem Variations
| Ecosystem | Manifest | Package manager | Test command |
|-----------|----------|-----------------|--------------|
| Node/JS | `package.json` | npm, pnpm, or Bun | `vitest` / `jest` |
| Python | `pyproject.toml` | uv | `pytest` |
| Rust | `Cargo.toml` | cargo | `cargo test` |
| Go | `go.mod` | go modules | `go test ./...` |
| Terraform | `.tf` files | providers | `terraform validate` |
Put `AGENTS.md` instructions for each ecosystem in the [Agent Instruction Files](agents-files.md) page.
## Monorepos
Use a workspace tool for monorepos:
* Turborepo or Nx for JavaScript/TypeScript.
* pnpm workspaces for dependency management.
* Cargo workspaces for Rust.
* Go workspaces for Go modules.
* uv workspaces for Python.
Put a nested `AGENTS.md` in each package when a monorepo has multiple packages.
## Citations
* [Trunk-Based Development](https://trunk-based-development.com/)
* [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow)
* [GitHub Actions](https://docs.github.com/en/actions)
* [Microsoft Engineering Playbook](https://microsoft.github.io/code-with-engineering-playbook/)
* [semver.org](https://semver.org/)
* [mise](https://mise.jdx.dev/)
* [Dev Container Specification](https://containers.dev/)
## See Also
* [Agent Instruction Files](agents-files.md)
* [Language and Framework Stacks](languages/index.md)
* [Infrastructure and Cloud](infra/index.md)
omp-docs/engineering/signal-remote.md
+116
View File
@@ -0,0 +1,116 @@
---
type: guide
title: Remote Control a Pi Instance with Signal
description: How to drive a self-hosted pi agent from Signal messages using signal-cli and a bridge layer.
tags:
- signal
- remote-control
- pi
- automation
- unverified
timestamp: 2026-08-11
---
verified: 2026-08-28
# Remote Control a Pi Instance with Signal
This page explains how to send a command to a self-hosted pi agent from a Signal message. Signal has no official bot API, so you must use an open-source bridge. The bridge delivers a Signal message to the agent and then returns the agent reply over Signal.
## Overview
```mermaid
flowchart LR
U[Signal client] -->|Signal message| B[signal-cli-rest-api]
B -->|WebSocket or REST| G[bridge layer]
G -->|stdin or webhook| P[pi agent]
P -->|reply| G
G -->|send| B
B -->|Signal message| U
```
## Signal Bridges
Signal provides no public bot platform. Use one of these open-source bridges.
### signal-cli
`signal-cli` is a Java command-line client. It runs in CLI, daemon, or JSON-RPC mode. Use it to register a number, link a device, send, and receive.
Install the GraalVM native build to avoid JVM startup time:
```bash
curl -L -O https://github.com/AsamK/signal-cli/releases/download/vVERSION/signal-cli-VERSION-Linux-native.tar.gz
```
Send a message:
```bash
signal-cli -a +1234567890 send -m "Hello" +0987654321
```
Receive messages:
```bash
signal-cli -a +1234567890 daemon --http=localhost:3000
```
The daemon exposes `POST /api/v1/rpc` and `GET /api/v1/events`.
Keep `signal-cli` updated. A release older than three months can break against the Signal server.
### signal-cli-rest-api
`signal-cli-rest-api` wraps `signal-cli` in a Docker container. It exposes REST endpoints and a WebSocket receive channel. This is the easiest bridge to deploy.
Run it with `MODE=json-rpc` for a single daemon with WebSocket receive. Send a message with `POST /v2/send`. Receive messages from `GET /v1/receive/<number>`.
### signald
`signald` is a lighter Rust alternative. It runs as a daemon and communicates over WebSocket. It uses fewer resources than the Java-based `signal-cli`.
## Bridge the Message to the Agent
Use one of these patterns to connect the Signal bridge to the pi agent.
* Webhook: the bridge posts the incoming message to the agent over HTTP.
* WebSocket: a script subscribes to incoming messages and calls the agent.
* File polling: a script writes each message to a file that the agent watches.
* JSON-RPC pipe: the agent runs as a child process of the `signal-cli` daemon.
Use a high-level framework to make the bridge simpler:
* `signalbot` in Python.
* `signal-rest-ts` in TypeScript.
## Account Setup
Use a dedicated number for the bot. Register the number as its own account, or link it to your phone as a linked device.
A primary account allows up to five linked devices. Use a dedicated secondary SIM or a landline for a self-contained bot.
Registration requires a captcha from the Signal captcha site. Verify with an SMS code. Use voice verification for landlines.
## Security and Gotchas
Protect the bot keys. The bridge stores cryptographic keys in its data directory. Anyone with access to that directory can impersonate the bot.
* Restrict the bridge to localhost.
* Use API tokens and IP filtering if you expose it.
* Use `secured-signal-api` as an authenticated gateway for internet access.
The Signal protocol expects regular receive calls. Use daemon mode or an auto-receive schedule to keep messages in sync. Do not combine REST receive and auto-receive, or you will get duplicate messages.
## Citations
* [signal-cli](https://github.com/AsamK/signal-cli)
* [signal-cli-rest-api](https://github.com/bbernhard/signal-cli-rest-api)
* [signald](https://pypi.org/project/signald/) (GitHub: <https://github.com/signald/signald> — archived)
* [signalbot](https://pypi.org/project/signalbot/)
* [signal-rest-ts](https://www.npmjs.com/package/signal-rest-ts) (unverified)
* [secured-signal-api](https://github.com/codeshelldev/secured-signal-api)
## See Also
* [Pi Configuration](../pi/index.md)
* [Pi Subagents](../pi/packages/pi-subagents.md)
* [Agent Instruction Files](agents-files.md)
omp-docs/engineering/skills-ecosystem.md
+144
View File
@@ -0,0 +1,144 @@
---
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)