From 93d7c7da571e04a7d5be120b1fa7468ac0dc3352 Mon Sep 17 00:00:00 2001 From: ulises-jeremias Date: Thu, 17 Sep 2026 18:01:15 -0300 Subject: [PATCH 1/6] Add v-development skill Teach Copilot V language development: toolchain, v.mod layout, build/test/fmt, and Option/Result error handling. --- docs/README.skills.md | 1 + skills/v-development/SKILL.md | 86 +++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 skills/v-development/SKILL.md diff --git a/docs/README.skills.md b/docs/README.skills.md index 24473fa6f4..9d4bb53c2e 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -430,6 +430,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [update-markdown-file-index](../skills/update-markdown-file-index/SKILL.md)
`gh skills install github/awesome-copilot update-markdown-file-index` | Update a markdown file section with an index/table of files from a specified folder. | None | | [update-specification](../skills/update-specification/SKILL.md)
`gh skills install github/awesome-copilot update-specification` | Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code. | None | | [upstash-redis](../skills/upstash-redis/SKILL.md)
`gh skills install github/awesome-copilot upstash-redis` | Use Redis over HTTP from serverless and edge runtimes with @upstash/redis, and add rate limiting with @upstash/ratelimit. Use when the user mentions Upstash Redis, needs Redis from a Next.js route handler or middleware, Vercel, Cloudflare Workers, Deno, or Bun without TCP connection pooling, or wants cache-aside with TTLs, a session store, counters, or a 429 rate limiter using fixed window, sliding window, or token bucket. DO NOT use for self-hosted or TCP Redis clients (ioredis, node-redis), Redis Cluster administration, or vector similarity search. | None | +| [v-development](../skills/v-development/SKILL.md)
`gh skills install github/awesome-copilot v-development` | Guide GitHub Copilot through V language development: installing the toolchain, project layout with v.mod, building, testing, formatting, and writing idiomatic V including Option/Result error handling. Use when the user works with V source files, v.mod projects, or asks about V syntax, tooling, and conventions. | None | | [vardoger-analyze](../skills/vardoger-analyze/SKILL.md)
`gh skills install github/awesome-copilot vardoger-analyze` | Use when the user asks to personalize the GitHub Copilot CLI assistant, adapt Copilot to their style, use vardoger, or analyze their Copilot CLI conversation history. Reads the local session directory at `~/.copilot/session-state/`, extracts recurring preferences and conventions, and writes a fenced personalization block into `~/.copilot/copilot-instructions.md`. Runs entirely on the user's machine via the local `vardoger` CLI (`pipx install vardoger`); no network calls and no uploads. Triggers: 'personalize my copilot', 'analyze my copilot history', 'tailor copilot to me', 'run vardoger', 'update my copilot instructions from history', 'make copilot learn my style'. | None | | [vcpkg](../skills/vcpkg/SKILL.md)
`gh skills install github/awesome-copilot vcpkg` | Guide for setting up vcpkg in C++ projects, managing dependency versions, and cross-compiling. Covers manifest initialization, CMake and Visual Studio integration, classic-to-manifest migration, version pinning, baselines, overrides, triplets, and cross-compilation. Use when a user is working with vcpkg project setup, installation, version management, or cross-platform builds. For specialized tasks, additional references cover custom registries and overlay ports (references/registries.md), CI/CD and binary caching (references/ci.md), and troubleshooting and dependency lifecycle (references/troubleshooting.md). | `references/ci.md`
`references/registries.md`
`references/troubleshooting.md` | | [verify-agent-action](../skills/verify-agent-action/SKILL.md)
`gh skills install github/awesome-copilot verify-agent-action` | Review a proposed AI-agent action or human-approval packet before execution. Use when an agent wants to run a consequential tool, command, deployment, message, purchase, credential operation, or data mutation; when checking whether approval still matches the exact action; or when auditing action evidence for forged results, parameter swaps, replay, correlated reviewers, missing evidence, expiry, or stale monitoring. Produce an evidence-based review only—never execute or authorize the action. | None | diff --git a/skills/v-development/SKILL.md b/skills/v-development/SKILL.md new file mode 100644 index 0000000000..60a89442ae --- /dev/null +++ b/skills/v-development/SKILL.md @@ -0,0 +1,86 @@ +--- +name: v-development +description: 'Guide GitHub Copilot through V language development: installing the toolchain, project layout with v.mod, building, testing, formatting, and writing idiomatic V including Option/Result error handling. Use when the user works with V source files, v.mod projects, or asks about V syntax, tooling, and conventions.' +--- + +You are a V language expert assistant. When a user asks about V (vlang), use the precise information below to give accurate, complete answers. + +V is a statically typed, compiled language with Go-like syntax. Official docs: . Third-party modules: . + +## Toolchain + +Install from (prebuilt binaries or build from source), then verify with `v --version`. + +| Task | Command | +|---|---| +| Run a program | `v run main.v` | +| Run a project | `v run .` (uses `v.mod`, see below) | +| Build a binary | `v -o app .` | +| Run tests | `v test .` (runs `*_test.v` files) | +| Format code | `v fmt -w file.v` | +| Static checks | `v vet .` | +| Install a module | `v install .` | +| Update modules | `v update` | + +Always run `v fmt -w` on files you touch and `v vet .` plus `v test .` before declaring work done. + +## Project layout + +Every project has a `v.mod` file at its root: + +```text +Module { + name: 'myapp' + version: '0.1.0' + deps: [] +} +``` + +Conventions: + +- `main.v` (or `module main`) is the entry point; `fn main()` starts execution. +- One module per directory; the directory name is the module name. +- Test files end in `_test.v` and contain `fn test_...() { assert ... }`. + +## Writing idiomatic V + +```v +module main + +struct Config { + host string +mut: + port int +} + +fn connect(cfg Config) !string { + if cfg.port == 0 { + return error('port is required') + } + return 'http://${cfg.host}:${cfg.port}' +} + +fn main() { + url := connect(host: 'localhost', port: 8080) or { + eprintln(err) + return + } + println(url) +} +``` + +Rules to follow when generating or editing V code: + +- **No null.** Absence is expressed with `Option` (`?Type`, value or `none`) and failures with `Result` (`!Type`). Handle them with `or { ... }` blocks; never invent null checks. +- **Immutable by default.** Struct fields and variables cannot be reassigned unless declared `mut:`. Function arguments are immutable; take `mut` receivers (`fn (mut s Struct)`) only when mutation is needed. +- **Explicit error propagation.** Functions that can fail declare `!ReturnType`. Callers must use `or { }`, `!` propagation, or `?` unwrapping. Do not ignore errors. +- **No globals.** Share state via struct fields, arguments, or dependency injection. +- **String interpolation** uses `'${expr}'` inside single-quoted strings. +- **C interop** is explicit: `#include`, `#flag`, and `C.func()` calls. Only suggest it when the user asks for system-level interop. +- Prefer the standard library (`os`, `json`, `net.http`, `time`, `flag`) before suggesting third-party modules. + +## Important behavioral rules + +- If the user's V version is unknown and a construct looks version-sensitive, ask or check with `v --version` first; V is pre-1.0 and syntax evolves. +- Never translate Go, Rust, or C idioms literally into V. Map the intent onto the rules above (e.g., Go `nil` error checks become V `or { }` blocks). +- When adding a dependency, record it in `v.mod` under `deps` and mention the `v install` command. From 76ff7d52ecaf06f288ba6493ab98ca162783d7ae Mon Sep 17 00:00:00 2001 From: ulises-jeremias Date: Thu, 17 Sep 2026 23:29:27 -0300 Subject: [PATCH 2/6] Fix v-development skill accuracy Correct v.mod schema (dependencies), manifest optionality, entry-point guidance, VPM registry URL, and globals rule per official V docs. --- skills/v-development/SKILL.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/skills/v-development/SKILL.md b/skills/v-development/SKILL.md index 60a89442ae..31004b75f8 100644 --- a/skills/v-development/SKILL.md +++ b/skills/v-development/SKILL.md @@ -5,7 +5,7 @@ description: 'Guide GitHub Copilot through V language development: installing th You are a V language expert assistant. When a user asks about V (vlang), use the precise information below to give accurate, complete answers. -V is a statically typed, compiled language with Go-like syntax. Official docs: . Third-party modules: . +V is a statically typed, compiled language with Go-like syntax. Official docs: . Standard library reference: . Third-party packages live in the VPM registry: . ## Toolchain @@ -14,32 +14,41 @@ Install from (prebuilt binaries or build from sourc | Task | Command | |---|---| | Run a program | `v run main.v` | -| Run a project | `v run .` (uses `v.mod`, see below) | +| Run a project folder | `v run .` (compiles every `.v` file in the folder) | | Build a binary | `v -o app .` | | Run tests | `v test .` (runs `*_test.v` files) | | Format code | `v fmt -w file.v` | | Static checks | `v vet .` | -| Install a module | `v install .` | -| Update modules | `v update` | +| Find a package | `v search ` (searches the VPM registry) | +| Install a package | `v install ` or `v install --git ` | +| Update packages | `v update` (all) or `v update ` | Always run `v fmt -w` on files you touch and `v vet .` plus `v test .` before declaring work done. ## Project layout -Every project has a `v.mod` file at its root: +Standalone V programs are single `.v` files and need no manifest: `v run hello.v` just works. +Structured projects and publishable packages use a `v.mod` file at the project root +as the module anchor (imports resolve relative to the folder containing it): ```text Module { name: 'myapp' + description: 'My nice package.' version: '0.1.0' - deps: [] + license: 'MIT' + dependencies: [] } ``` Conventions: -- `main.v` (or `module main`) is the entry point; `fn main()` starts execution. -- One module per directory; the directory name is the module name. +- An executable application uses `module main`, and its entry function is `fn main()`. + The source file is commonly named `main.v`, but the filename is not what defines + the entry point — the `main` module and `main()` function do. (In single-file + programs, `fn main()` may even be omitted; top-level statements run implicitly.) +- A folder of `.v` files declaring the same module compiles together with `v run .`. +- Keep one module per directory; the module name conventionally matches the directory. - Test files end in `_test.v` and contain `fn test_...() { assert ... }`. ## Writing idiomatic V @@ -74,7 +83,7 @@ Rules to follow when generating or editing V code: - **No null.** Absence is expressed with `Option` (`?Type`, value or `none`) and failures with `Result` (`!Type`). Handle them with `or { ... }` blocks; never invent null checks. - **Immutable by default.** Struct fields and variables cannot be reassigned unless declared `mut:`. Function arguments are immutable; take `mut` receivers (`fn (mut s Struct)`) only when mutation is needed. - **Explicit error propagation.** Functions that can fail declare `!ReturnType`. Callers must use `or { }`, `!` propagation, or `?` unwrapping. Do not ignore errors. -- **No globals.** Share state via struct fields, arguments, or dependency injection. +- **No globals by default.** Global variables are disabled by default and should generally be avoided in normal application code; share state via struct fields, arguments, or dependency injection. V can enable them explicitly (`__global` declarations with the `-enable-globals` compiler flag) for specialized low-level use cases. - **String interpolation** uses `'${expr}'` inside single-quoted strings. - **C interop** is explicit: `#include`, `#flag`, and `C.func()` calls. Only suggest it when the user asks for system-level interop. - Prefer the standard library (`os`, `json`, `net.http`, `time`, `flag`) before suggesting third-party modules. @@ -83,4 +92,4 @@ Rules to follow when generating or editing V code: - If the user's V version is unknown and a construct looks version-sensitive, ask or check with `v --version` first; V is pre-1.0 and syntax evolves. - Never translate Go, Rust, or C idioms literally into V. Map the intent onto the rules above (e.g., Go `nil` error checks become V `or { }` blocks). -- When adding a dependency, record it in `v.mod` under `deps` and mention the `v install` command. +- When adding a dependency, record it in `v.mod` under `dependencies` and mention the `v install` command. VPM package names may carry a publisher prefix and are normalized on install (e.g. installed under `~/.vmodules`); check the package's VPM page for its exact install name and import path. From 5af43f5a9423b2006f8e8cac61730b88974f654e Mon Sep 17 00:00:00 2001 From: ulises-jeremias Date: Fri, 18 Sep 2026 00:56:35 -0300 Subject: [PATCH 3/6] Correct mutability and Option/Result propagation guidance Variables use mut, only struct sections use mut:; postfix ? propagates Options, ! propagates errors; no forced unwrap. --- skills/v-development/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/v-development/SKILL.md b/skills/v-development/SKILL.md index 31004b75f8..176a0e2ba2 100644 --- a/skills/v-development/SKILL.md +++ b/skills/v-development/SKILL.md @@ -81,8 +81,8 @@ fn main() { Rules to follow when generating or editing V code: - **No null.** Absence is expressed with `Option` (`?Type`, value or `none`) and failures with `Result` (`!Type`). Handle them with `or { ... }` blocks; never invent null checks. -- **Immutable by default.** Struct fields and variables cannot be reassigned unless declared `mut:`. Function arguments are immutable; take `mut` receivers (`fn (mut s Struct)`) only when mutation is needed. -- **Explicit error propagation.** Functions that can fail declare `!ReturnType`. Callers must use `or { }`, `!` propagation, or `?` unwrapping. Do not ignore errors. +- **Immutable by default.** Variables need `mut` to be reassigned (`mut x := 1`); struct fields are grouped under `mut:` sections to allow mutation, and changing a field additionally requires a mutable struct instance (`mut cfg := ...`). Function arguments are immutable; take `mut` receivers (`fn (mut s Struct)`) only when mutation is needed. +- **Explicit error propagation.** Functions that can fail declare `!ReturnType` (or `?Type` for absence). Handle results with `or { }` blocks, propagate with postfix `!` (errors) or `?` (options; the enclosing function must also return one), or unwrap options with `if x := opt() { }`. V has no forced unwrap. Do not ignore errors. - **No globals by default.** Global variables are disabled by default and should generally be avoided in normal application code; share state via struct fields, arguments, or dependency injection. V can enable them explicitly (`__global` declarations with the `-enable-globals` compiler flag) for specialized low-level use cases. - **String interpolation** uses `'${expr}'` inside single-quoted strings. - **C interop** is explicit: `#include`, `#flag`, and `C.func()` calls. Only suggest it when the user asks for system-level interop. From 8fb241f8556228612206ac797be7ff32fba1496a Mon Sep 17 00:00:00 2001 From: ulises-jeremias Date: Fri, 18 Sep 2026 01:12:26 -0300 Subject: [PATCH 4/6] Scope compilation, nil, and mutability guidance to verified behavior v run excludes test files; nil only in unsafe/C interop; mutable parameters documented. --- skills/v-development/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/v-development/SKILL.md b/skills/v-development/SKILL.md index 176a0e2ba2..0931253ee7 100644 --- a/skills/v-development/SKILL.md +++ b/skills/v-development/SKILL.md @@ -14,7 +14,7 @@ Install from (prebuilt binaries or build from sourc | Task | Command | |---|---| | Run a program | `v run main.v` | -| Run a project folder | `v run .` (compiles every `.v` file in the folder) | +| Run a project folder | `v run .` (compiles the folder's program files; `*_test.v` files are built separately via `v test .`) | | Build a binary | `v -o app .` | | Run tests | `v test .` (runs `*_test.v` files) | | Format code | `v fmt -w file.v` | @@ -80,8 +80,8 @@ fn main() { Rules to follow when generating or editing V code: -- **No null.** Absence is expressed with `Option` (`?Type`, value or `none`) and failures with `Result` (`!Type`). Handle them with `or { ... }` blocks; never invent null checks. -- **Immutable by default.** Variables need `mut` to be reassigned (`mut x := 1`); struct fields are grouped under `mut:` sections to allow mutation, and changing a field additionally requires a mutable struct instance (`mut cfg := ...`). Function arguments are immutable; take `mut` receivers (`fn (mut s Struct)`) only when mutation is needed. +- **No null in ordinary code.** In ordinary safe V application code, model absence with `Option` (`?Type`, value or `none`) rather than nullable values; failures use `Result` (`!Type`). Handle them with `or { ... }` blocks; never invent null checks. Pointer-level `nil` exists only in low-level `unsafe`/C-interop contexts (e.g. `unsafe { nil }`) and should not be treated as ordinary application-level optionality. +- **Immutable by default.** Variables need `mut` to be reassigned (`mut x := 1`); struct fields are grouped under `mut:` sections to allow mutation, and changing a field additionally requires a mutable struct instance (`mut cfg := ...`). Function arguments are immutable by default; mutate via `mut` receivers (`fn (mut s Struct)`) or mutable parameters for complex values (`fn f(mut arr []int)`, called as `f(mut arr)`). Only complex types such as arrays and maps may be modified this way, and returning values is preferred over modifying arguments. - **Explicit error propagation.** Functions that can fail declare `!ReturnType` (or `?Type` for absence). Handle results with `or { }` blocks, propagate with postfix `!` (errors) or `?` (options; the enclosing function must also return one), or unwrap options with `if x := opt() { }`. V has no forced unwrap. Do not ignore errors. - **No globals by default.** Global variables are disabled by default and should generally be avoided in normal application code; share state via struct fields, arguments, or dependency injection. V can enable them explicitly (`__global` declarations with the `-enable-globals` compiler flag) for specialized low-level use cases. - **String interpolation** uses `'${expr}'` inside single-quoted strings. From a6099f84ce8917ed38b959aeb6422c24c2fce6b6 Mon Sep 17 00:00:00 2001 From: ulises-jeremias Date: Fri, 18 Sep 2026 01:24:58 -0300 Subject: [PATCH 5/6] Keep example Config fields immutable The port field was never mutated; placing it under mut: contradicted the immutable-by-default guidance. --- skills/v-development/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/v-development/SKILL.md b/skills/v-development/SKILL.md index 0931253ee7..3f3ee4c6ed 100644 --- a/skills/v-development/SKILL.md +++ b/skills/v-development/SKILL.md @@ -58,7 +58,6 @@ module main struct Config { host string -mut: port int } From ee3ae0cd59fabc41da1134307fed7403b9a072a9 Mon Sep 17 00:00:00 2001 From: ulises-jeremias Date: Fri, 18 Sep 2026 01:29:38 -0300 Subject: [PATCH 6/6] Recommend json2 over superseded json module Official V docs teach json2 for encoding/decoding. --- skills/v-development/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/v-development/SKILL.md b/skills/v-development/SKILL.md index 3f3ee4c6ed..3d581b3a3a 100644 --- a/skills/v-development/SKILL.md +++ b/skills/v-development/SKILL.md @@ -85,7 +85,7 @@ Rules to follow when generating or editing V code: - **No globals by default.** Global variables are disabled by default and should generally be avoided in normal application code; share state via struct fields, arguments, or dependency injection. V can enable them explicitly (`__global` declarations with the `-enable-globals` compiler flag) for specialized low-level use cases. - **String interpolation** uses `'${expr}'` inside single-quoted strings. - **C interop** is explicit: `#include`, `#flag`, and `C.func()` calls. Only suggest it when the user asks for system-level interop. -- Prefer the standard library (`os`, `json`, `net.http`, `time`, `flag`) before suggesting third-party modules. +- Prefer the standard library (`os`, `json2`, `net.http`, `time`, `flag`) before suggesting third-party modules. Note: the current `json` module is superseded by `json2`; do not recommend `import json` in new code. ## Important behavioral rules