diff --git a/docs/README.skills.md b/docs/README.skills.md index a95979868..7a39dc539 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -431,6 +431,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 000000000..3d581b3a3 --- /dev/null +++ b/skills/v-development/SKILL.md @@ -0,0 +1,94 @@ +--- +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: . Standard library reference: . Third-party packages live in the VPM registry: . + +## 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 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` | +| Static checks | `v vet .` | +| 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 + +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' + license: 'MIT' + dependencies: [] +} +``` + +Conventions: + +- 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 + +```v +module main + +struct Config { + host string + 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 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. +- **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`, `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 + +- 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 `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.