pi-rust-skills 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## Unreleased
+
+- Expanded all existing Rust skills with project-context discovery, workspace-aware validation, and domain-specific safety guidance.
+- Added Rust skills for web APIs, databases, embedded/no_std, procedural macros, and build/cross-compilation.
+- Updated README skill selection guidance and example prompts for all bundled skills.
+
+## 0.1.0
+
+- Initial npm-ready Pi package bootstrap.
+- Added Rust project context extension tool.
+- Added 13 Rust skills covering project bootstrap, code review, debugging, testing, Tokio async, CLI, WASM, FFI, performance, security, crate publishing, refactoring, and CI/toolchain setup.
+- Added validation and skill listing scripts.

package/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+## Local checks
+
+```bash
+npm test
+npm run list
+npm pack --dry-run
+```
+
+## Skill rules
+
+Each skill must live in its own directory with a `SKILL.md` file and valid frontmatter:
+
+```yaml
+---
+name: lowercase-skill-name
+description: Specific trigger description explaining when Pi should use this skill.
+license: MIT
+---
+```
+
+Use lowercase letters, numbers, and hyphens for skill names. Keep descriptions specific so Pi loads the right skill at the right time.
+
+## Release process
+
+1. Update `CHANGELOG.md`.
+2. Update `package.json` version.
+3. Run `npm test`.
+4. Run `npm pack --dry-run` and verify the files list.
+5. Publish with `npm publish --access public`.
+6. Create a matching git tag.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gripebomb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# pi-rust-skills
+
+Rust programming skills and a lightweight Rust project context tool for [Pi Coding Agent](https://pi.dev/).
+
+This package is meant to be published to npm and installed by Pi users with:
+
+```bash
+pi install npm:pi-rust-skills
+```
+
+For a scoped package, rename the package to something like `@gripebomb/pi-rust-skills` and install it with:
+
+```bash
+pi install npm:@gripebomb/pi-rust-skills
+```
+
+## What it includes
+
+### Extension tool
+
+- `rust_project_context` — read-only helper that inspects a Rust/Cargo project and returns:
+  - Rust/Cargo/rustup/rustfmt/clippy version information.
+  - Cargo.toml preview.
+  - `cargo metadata --no-deps` output.
+  - Optional `cargo tree -e features` output.
+
+### Skills
+
+| Skill | Purpose |
+|---|---|
+| `/skill:rust-project-bootstrap` | Create or restructure Rust crates/workspaces. |
+| `/skill:rust-code-review` | Review Rust code for correctness, idioms, safety, and maintainability. |
+| `/skill:rust-debugging` | Diagnose compiler errors, panics, failing tests, and Cargo issues. |
+| `/skill:rust-testing` | Add unit, integration, doc, async, property, and regression tests. |
+| `/skill:rust-async-tokio` | Build/review Tokio and async Rust systems. |
+| `/skill:rust-cli` | Build Rust command-line applications. |
+| `/skill:rust-web-api` | Build Rust HTTP APIs and web services. |
+| `/skill:rust-database` | Build Rust database layers, migrations, and query tests. |
+| `/skill:rust-wasm` | Build Rust WebAssembly projects. |
+| `/skill:rust-ffi` | Implement and review Rust FFI boundaries. |
+| `/skill:rust-embedded-no-std` | Build embedded and no_std Rust projects. |
+| `/skill:rust-proc-macro` | Build and test Rust procedural macros. |
+| `/skill:rust-build-cross` | Configure build scripts, native dependencies, and cross-compilation. |
+| `/skill:rust-performance` | Profile and optimize Rust code. |
+| `/skill:rust-security-audit` | Audit Rust projects for security issues. |
+| `/skill:rust-crate-publishing` | Prepare crates for crates.io publishing. |
+| `/skill:rust-refactor-migration` | Safely refactor and modernize Rust codebases. |
+| `/skill:rust-toolchain-ci` | Configure Rust toolchains, lint policy, and CI. |
+
+### Skill selection guide
+
+- Start with `/skill:rust-project-bootstrap` for new crates, workspaces, or major project reshaping.
+- Use `/skill:rust-debugging` when a command fails, code panics, or behavior is wrong.
+- Use `/skill:rust-code-review` for risk-focused review before merging or publishing.
+- Use `/skill:rust-testing` when the main task is coverage, regression tests, or test strategy.
+- Use a domain skill when the code has a clear surface: `/skill:rust-cli`, `/skill:rust-web-api`, `/skill:rust-database`, `/skill:rust-async-tokio`, `/skill:rust-wasm`, `/skill:rust-ffi`, `/skill:rust-embedded-no-std`, `/skill:rust-proc-macro`, or `/skill:rust-build-cross`.
+- Use `/skill:rust-performance`, `/skill:rust-security-audit`, `/skill:rust-crate-publishing`, `/skill:rust-refactor-migration`, or `/skill:rust-toolchain-ci` for cross-cutting project work.
+
+### Skills that combine well
+
+- CLI or web API work often pairs with `/skill:rust-testing`, `/skill:rust-toolchain-ci`, and `/skill:rust-crate-publishing`.
+- Async services often pair `/skill:rust-async-tokio` with `/skill:rust-web-api`, `/skill:rust-database`, and `/skill:rust-performance`.
+- FFI, embedded, proc macro, and cross-build tasks often pair with `/skill:rust-security-audit` and `/skill:rust-testing`.
+- Release preparation often pairs `/skill:rust-crate-publishing` with `/skill:rust-code-review`, `/skill:rust-security-audit`, and `/skill:rust-toolchain-ci`.
+
+## Local development
+
+```bash
+git clone https://github.com/gripebomb/pi-rust-skills.git
+cd pi-rust-skills
+npm test
+npm run list
+```
+
+Try it locally in Pi:
+
+```bash
+pi install ./pi-rust-skills
+# or from inside the parent directory:
+pi -e ./pi-rust-skills
+```
+
+Then invoke a skill:
+
+```text
+/skill:rust-code-review Review this Rust project and suggest fixes.
+```
+
+## Package structure
+
+```text
+pi-rust-skills/
+├── extensions/
+│   └── rust-skills.ts
+├── skills/
+│   ├── rust-project-bootstrap/SKILL.md
+│   ├── rust-code-review/SKILL.md
+│   └── ...
+├── references/
+├── scripts/
+├── examples/
+├── package.json
+└── README.md
+```
+
+Pi discovers resources through the `pi` manifest in `package.json`:
+
+```json
+{
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"]
+  }
+}
+```
+
+## Publishing to npm
+
+Before publishing, update these fields in `package.json`:
+
+- `name` if you want a scoped package, for example `@gripebomb/pi-rust-skills`.
+- `author`.
+- `repository`, `homepage`, and `bugs`.
+- `version`.
+
+Then run:
+
+```bash
+npm test
+npm pack --dry-run
+npm login
+npm publish --access public
+```
+
+After npm publication, install through Pi:
+
+```bash
+pi install npm:pi-rust-skills
+```
+
+If you publish as a scoped package:
+
+```bash
+pi install npm:@gripebomb/pi-rust-skills
+```
+
+## Getting listed on pi.dev/packages
+
+Pi's package catalog displays npm packages tagged with the `pi-package` keyword. This package already includes that keyword and a `pi` manifest.
+
+The catalog appears to crawl npm metadata; after publishing, allow time for the package page to update. Use a clear npm description because the catalog shows package names, descriptions, resource types, npm links, repository links, and install commands.
+
+## Security notes
+
+Pi packages can execute code and influence agent behavior. This package keeps the bundled extension read-only and uses skills as instruction files, but users should still review package contents before installing.
+
+The `rust_project_context` tool runs read-only commands such as `rustc --version`, `cargo --version`, `cargo metadata --no-deps`, and optionally `cargo tree -e features`.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Open a private security advisory on the repository if available, or email the maintainer listed in the package metadata.
+
+## Package behavior
+
+The extension included in this package is intentionally read-only. It inspects Rust project metadata and toolchain versions. It does not write files, delete files, send network traffic, or publish crates.
+
+The skills are instruction documents. They can guide an agent to run commands in a user's project, so users should review the skill contents before installing or invoking them.
+
+## Maintainer checklist
+
+- Keep extension tools read-only unless a future version clearly documents write behavior.
+- Avoid adding install scripts to `package.json`.
+- Keep dependencies minimal.
+- Review generated or contributed skills for dangerous instructions.

package/examples/prompts.md

@@ -0,0 +1,75 @@
+# Example Prompts
+
+Use these prompts in Pi after installing the package.
+
+```text
+/skill:rust-project-bootstrap Create a new Rust CLI called log-sifter that reads stdin and filters lines with clap flags.
+```
+
+```text
+/skill:rust-code-review Review this Rust workspace for ownership problems, API compatibility risks, unwraps in production code, and missing tests.
+```
+
+```text
+/skill:rust-debugging Fix the current borrow checker error without adding unnecessary clones, then rerun the original failing command.
+```
+
+```text
+/skill:rust-testing Add tests around the parser module and create a failing regression test for the bug in issue #12.
+```
+
+```text
+/skill:rust-async-tokio Review this Tokio worker pool for cancellation, backpressure, and lock-across-await risks.
+```
+
+```text
+/skill:rust-cli Add a `scan` subcommand with stable JSON output, documented exit codes, and integration tests.
+```
+
+```text
+/skill:rust-web-api Add an Axum endpoint for creating projects with validation errors, tracing, and HTTP integration tests.
+```
+
+```text
+/skill:rust-database Add SQLx migrations and repository tests for storing job runs with transaction rollback on failure.
+```
+
+```text
+/skill:rust-wasm Build this crate for the browser with wasm-bindgen, TypeScript declarations, and wasm-pack tests.
+```
+
+```text
+/skill:rust-ffi Review this C ABI boundary for ownership transfer, null pointer handling, panic safety, and generated headers.
+```
+
+```text
+/skill:rust-embedded-no-std Make this driver crate no_std-compatible and add target build checks plus host-side tests.
+```
+
+```text
+/skill:rust-proc-macro Add a derive macro with trybuild compile-fail tests and inspect the expanded output.
+```
+
+```text
+/skill:rust-build-cross Fix this build.rs script so it handles pkg-config, rerun directives, and Linux/macOS/Windows targets.
+```
+
+```text
+/skill:rust-performance Profile this parser, add a Criterion benchmark, and only optimize changes that improve the baseline.
+```
+
+```text
+/skill:rust-security-audit Audit this crate for path traversal, command injection, unsafe code, and dependency issues.
+```
+
+```text
+/skill:rust-crate-publishing Prepare this crate for crates.io. Do not publish; only perform dry-run checks.
+```
+
+```text
+/skill:rust-refactor-migration Split the large `client` module into smaller modules while preserving the public API and adding compatibility re-exports.
+```
+
+```text
+/skill:rust-toolchain-ci Add GitHub Actions for fmt, clippy, tests, docs, MSRV, and npm package validation for this Pi package.
+```

package/extensions/rust-skills.ts

@@ -0,0 +1,182 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { execFile } from "node:child_process";
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const MAX_STDOUT = 80_000;
+const MAX_FILE_PREVIEW = 24_000;
+
+type RunResult = {
+  ok: boolean;
+  command: string;
+  stdout: string;
+  stderr: string;
+  error?: string;
+};
+
+type RustProjectContextParams = {
+  cwd?: string;
+  includeMetadata?: boolean;
+  includeTree?: boolean;
+  includeCargoToml?: boolean;
+};
+
+async function exists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function truncate(value: string, max = MAX_STDOUT): string {
+  if (value.length <= max) return value;
+  return `${value.slice(0, max)}\n\n[truncated ${value.length - max} characters]`;
+}
+
+async function run(command: string, args: string[], cwd: string, timeout = 20_000): Promise<RunResult> {
+  try {
+    const result = await execFileAsync(command, args, {
+      cwd,
+      timeout,
+      maxBuffer: MAX_STDOUT * 2,
+      windowsHide: true,
+    });
+
+    return {
+      ok: true,
+      command: [command, ...args].join(" "),
+      stdout: truncate(result.stdout ?? ""),
+      stderr: truncate(result.stderr ?? ""),
+    };
+  } catch (error) {
+    const err = error as Error & { stdout?: string; stderr?: string; code?: string | number };
+    return {
+      ok: false,
+      command: [command, ...args].join(" "),
+      stdout: truncate(err.stdout ?? ""),
+      stderr: truncate(err.stderr ?? ""),
+      error: err.message,
+    };
+  }
+}
+
+function section(title: string, body: string): string {
+  return `## ${title}\n\n${body.trim() || "(no output)"}`;
+}
+
+function formatRun(result: RunResult): string {
+  const status = result.ok ? "ok" : "failed";
+  const parts = [`$ ${result.command}`, `status: ${status}`];
+
+  if (result.error) parts.push(`error: ${result.error}`);
+  if (result.stdout.trim()) parts.push(`stdout:\n${result.stdout.trim()}`);
+  if (result.stderr.trim()) parts.push(`stderr:\n${result.stderr.trim()}`);
+
+  return parts.join("\n");
+}
+
+async function readOptionalCargoToml(cwd: string): Promise<string> {
+  const cargoToml = path.join(cwd, "Cargo.toml");
+  if (!(await exists(cargoToml))) return "Cargo.toml not found in this directory.";
+
+  const content = await readFile(cargoToml, "utf8");
+  return truncate(content, MAX_FILE_PREVIEW);
+}
+
+export default function rustSkillsExtension(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "rust_project_context",
+    label: "Rust Project Context",
+    description:
+      "Inspect a Rust project or workspace using read-only Rust/Cargo commands and return toolchain, manifest, metadata, and dependency context.",
+    promptSnippet: "Inspect Rust/Cargo project context before planning Rust code changes.",
+    promptGuidelines: [
+      "Use rust_project_context when the user asks to change, review, debug, test, or publish an existing Rust project and Cargo.toml is likely present.",
+      "Use rust_project_context output to choose the right Rust skill, target crate, feature flags, workspace member, and validation commands.",
+      "Do not use rust_project_context as a replacement for reading source files; it only provides project-level context.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.Optional(
+        Type.String({
+          description:
+            "Directory to inspect. Defaults to the current working directory where Pi is running.",
+        }),
+      ),
+      includeMetadata: Type.Optional(
+        Type.Boolean({
+          description:
+            "Run cargo metadata --no-deps --format-version 1. Defaults to true.",
+        }),
+      ),
+      includeTree: Type.Optional(
+        Type.Boolean({
+          description:
+            "Run cargo tree -e features. Defaults to false because it can be noisy on large projects.",
+        }),
+      ),
+      includeCargoToml: Type.Optional(
+        Type.Boolean({
+          description: "Include a preview of Cargo.toml. Defaults to true.",
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params: RustProjectContextParams) {
+      const cwd = path.resolve(params.cwd ?? process.cwd());
+      const includeMetadata = params.includeMetadata ?? true;
+      const includeTree = params.includeTree ?? false;
+      const includeCargoToml = params.includeCargoToml ?? true;
+
+      const cargoTomlPath = path.join(cwd, "Cargo.toml");
+      const hasCargoToml = await exists(cargoTomlPath);
+
+      const checks: string[] = [];
+      checks.push(`cwd: ${cwd}`);
+      checks.push(`Cargo.toml: ${hasCargoToml ? cargoTomlPath : "not found"}`);
+
+      const outputs: string[] = [section("Rust workspace detection", checks.join("\n"))];
+
+      const versionCommands: Array<[string, string[]]> = [
+        ["rustc", ["--version"]],
+        ["cargo", ["--version"]],
+        ["rustup", ["show", "active-toolchain"]],
+        ["rustfmt", ["--version"]],
+        ["cargo", ["clippy", "--version"]],
+      ];
+
+      const versionResults = await Promise.all(versionCommands.map(([cmd, args]) => run(cmd, args, cwd, 10_000)));
+      outputs.push(section("Toolchain", versionResults.map(formatRun).join("\n\n")));
+
+      if (includeCargoToml) {
+        outputs.push(section("Cargo.toml preview", await readOptionalCargoToml(cwd)));
+      }
+
+      if (hasCargoToml && includeMetadata) {
+        const metadata = await run("cargo", ["metadata", "--no-deps", "--format-version", "1"], cwd, 30_000);
+        outputs.push(section("cargo metadata --no-deps", formatRun(metadata)));
+      }
+
+      if (hasCargoToml && includeTree) {
+        const tree = await run("cargo", ["tree", "-e", "features"], cwd, 30_000);
+        outputs.push(section("cargo tree -e features", formatRun(tree)));
+      }
+
+      const text = outputs.join("\n\n---\n\n");
+
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          cwd,
+          hasCargoToml,
+          includeMetadata,
+          includeTree,
+          includeCargoToml,
+        },
+      };
+    },
+  });
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "pi-rust-skills",
+  "version": "0.1.0",
+  "description": "Rust programming skills and a lightweight Rust project context tool for Pi Coding Agent.",
+  "type": "module",
+  "license": "MIT",
+  "author": "gripebomb",
+  "homepage": "https://github.com/gripebomb/pi-rust-skills#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gripebomb/pi-rust-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gripebomb/pi-rust-skills/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "agent-skills",
+    "skills",
+    "rust",
+    "cargo",
+    "clippy",
+    "rustfmt",
+    "tokio"
+  ],
+  "files": [
+    "extensions/",
+    "skills/",
+    "references/",
+    "scripts/",
+    "examples/",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./extensions/rust-skills.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "list": "node ./scripts/list-skills.mjs",
+    "test": "node ./scripts/validate-skills.mjs",
+    "validate": "node ./scripts/validate-skills.mjs",
+    "pack:dry": "npm pack --dry-run",
+    "prepack": "node ./scripts/validate-skills.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {},
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/RUST_AGENT_GUIDE.md

@@ -0,0 +1,72 @@
+# Rust Agent Guide
+
+This package is designed to make Pi Coding Agent better at Rust work without forcing every Rust instruction into the base prompt. Pi loads skill descriptions at startup and the full skill content only when a task matches or when the user invokes `/skill:name`.
+
+## Recommended agent flow
+
+1. Inspect the repository shape.
+2. If a Cargo project is present, call `rust_project_context`.
+3. Read the most relevant skill:
+   - New project: `/skill:rust-project-bootstrap`
+   - Review: `/skill:rust-code-review`
+   - Build failure: `/skill:rust-debugging`
+   - Tests: `/skill:rust-testing`
+   - Async: `/skill:rust-async-tokio`
+   - CLI: `/skill:rust-cli`
+   - Web APIs: `/skill:rust-web-api`
+   - Database work: `/skill:rust-database`
+   - WASM: `/skill:rust-wasm`
+   - FFI: `/skill:rust-ffi`
+   - Embedded/no_std: `/skill:rust-embedded-no-std`
+   - Proc macros: `/skill:rust-proc-macro`
+   - Build scripts/cross-compilation: `/skill:rust-build-cross`
+   - Performance: `/skill:rust-performance`
+   - Security: `/skill:rust-security-audit`
+   - Publishing crates: `/skill:rust-crate-publishing`
+   - Refactors: `/skill:rust-refactor-migration`
+   - CI/toolchain: `/skill:rust-toolchain-ci`
+4. Make small, testable changes.
+5. Run `cargo fmt`, `cargo clippy`, and `cargo test` when practical.
+6. Report what changed and what validation passed.
+
+## Default validation commands
+
+Use the narrowest command that proves the change, then broaden if the change is cross-cutting.
+
+```bash
+cargo fmt
+cargo check --all-targets --all-features
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+```
+
+For workspaces:
+
+```bash
+cargo check --workspace --all-targets --all-features
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo test --workspace --all-features
+```
+
+## Dependency policy
+
+Do not add dependencies by default. Add a dependency only when it meaningfully reduces risk, complexity, or maintenance burden. Prefer well-maintained crates with clear licensing, active releases, and a small feature surface.
+
+## Safety policy for generated Rust
+
+- No `unsafe` unless the task requires it.
+- No `unwrap` or `expect` in production code unless the invariant is documented and truly unrecoverable.
+- No network calls, file deletes, or shell execution in tests unless explicitly required and sandboxed.
+- Prefer deterministic tests.
+
+## Reporting format
+
+For substantial tasks, end with:
+
+```markdown
+## What changed
+
+## Validation
+
+## Notes and follow-ups
+```