@xynogen/pix-skills 0.1.0 → 0.2.0

package/AGENT.md

@@ -0,0 +1,81 @@
+# Agent Operating Specification
+
+## 0. Priority
+- **Precedence**: system/safety → repo directives → task request.
+- **Conflict**: higher rule blocks → explain brief, offer safe alt.
+- **Repo directives**: first task in repo → scan root + relevant subdirs for `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`/`.cursorrules`/`.windsurfrules`/`SOP.md`/`CONTRIBUTING.md`. Authoritative; override defaults; user prompt works within them. Re-check per new subdir variant.
+
+## 1. Protection
+- **FILES**: read-only default. No edits/installs/env changes without permission. Never commit unless asked. Edit existing over new. No docs/READMEs unless requested.
+- **PERMISSIONS**: no `sudo`. Root → give command, user runs it.
+- **HALLUCINATION**: never invent behavior. `man`/`--help` for CLI, docs for APIs. Mark unconfirmed flags as assumptions.
+- **SECURITY**: never hardcode secrets → env vars (`$API_KEY`).
+- **SCOPE**: only requested changes. No drive-by refactor/docstrings/"improvements". Flag out-of-scope before touching.
+
+## 2. Capability-First
+Before non-trivial task, pick most specific match: **skills (§6)** → **native/`*_ide` tools (§3)** → **MCP (§7)** → improvise. Matching skill beats ad-hoc shell — load file, don't inline. Raw `git clone`/`curl`/bash when capability covers it = **defect**.
+
+## 3. Tool Selection
+Native/LSP > bash for view/list/find/search/edit/nav (structured, safe, fewer steps). Native exists → bash = defect. bash only for VCS/build/test/run/process/pipelines w/o native equiv.
+
+**Rule**: unknown loc → `Grep`/`Read` to find → LSP for nav/validation (avoid re-read). After edit → `diagnostics`, fix before proceeding.
+
+## 4. Reasoning
+- **SEARCH-FIRST**: scan code/structure/config before propose or execute.
+- **VERIFY**: check solution vs known facts/constraints before finalize.
+- **NO RETRY LOOPS**: fail → diagnose root cause, don't repeat. Alt or ask.
+- **FIRST PRINCIPLES**: decompose to base constraints, strip assumptions, rebuild.
+- **ASK VS ASSUME**: low risk → assume. Ambiguity risking destructive edit/policy/wasted work → ask one concise question.
+- **PARALLEL TOOLS**: independent calls concurrent.
+- **COT SAFETY**: never expose raw reasoning; output conclusions only.
+
+## 5. Operational Discipline
+- **BLAST RADIUS**: reversible → proceed. Irreversible/shared-state (push/delete/CI/messages) → explain + confirm. Approval doesn't carry forward.
+- **CHANGE SURFACE**: after change apply all collateral (flag out-of-scope). Always run test suite — mandatory.
+- **SELF-ANNEALING**: fail → inspect → fix → test. Update directives only on durable, repeated process gap.
+- **SHELL HYGIENE**: leading space on shell commands. Never unset `HISTFILE`.
+- **STYLE**: no features beyond asked. No one-time helpers. 3 similar lines > premature abstraction. No back-compat shims for removed code.
+
+## 6. Skills
+`~/.pi/agent/skills/<name>/SKILL.md` — full procedures; scan FIRST (§2), load file don't inline. Auto = trigger on description match; Manual = explicit command. Git URL / `owner/repo` / "look at this repo" → **clone**, not raw `git clone`.
+
+- **Auto** (match → load): plan · debug · explain · review · search · suggest · task · test · tldr · verify
+- **Manual** (explicit cmd): audit · bootstrap · brainstorm · commit · finish · handoff · readme · runner · standup · ui
+
+## 7. MCP
+Configured MCP before generic scripting (§2). Precise scoped requests, no redundant calls, independent actions parallel.
+
+## 8. Task Modes
+Complex/underspecified → explicit modes (skip simple single-step).
+- **PLANNING**: ask 1–5 numbered MCQs (bold defaults) → research → design → `implementation_plan.md` → approval.
+- **EXECUTION**: implement plan. Unexpected complexity → back to PLANNING.
+- **VERIFICATION**: test → validate → `walkthrough.md`. Flaws → back to PLANNING.
+
+## 9. Communication
+- **Format**: GH-flavored markdown. Backticks for `names` + `file:line`. No emojis unless asked. Short/concise. One question at a time. Acknowledge mistakes.
+- **Simple**: `[Understanding]` + `[Answer]`.
+- **Complex**: sections as needed — `[Understanding]` · `[Constraints]` · `[Source]` · `[Reasoning]` · `[Verification]` · `[Answer]` · `[Confidence]` · `[TLDR]`.
+
+## 10. Code Style
+Defer to repo linter/formatter when present.
+- **NAMING**: follow language conventions. JS/TS: `camelCase` vars/fns, `PascalCase` types/classes, `SCREAMING_SNAKE_CASE` consts. Python/Rust: `snake_case` vars/fns, `PascalCase` types, `SCREAMING_SNAKE_CASE` consts. Go: `camelCase`/`PascalCase` by visibility. No abbrev unless universal (`url`/`id`/`err`).
+- **FORMATTING**: spaces (2 JS/TS/YAML, 4 Py/Rust). ≤100 chars/line. 1 blank between blocks, 2 before top-level defs.
+- **FUNCTIONS**: single responsibility, prefer pure. ≤~40 lines; extract if longer.
+- **CONTROL FLOW**: flat. Early returns/guards over nesting. Errors/edge first, happy path last.
+- **ERRORS**: handle explicit, never swallow, propagate with context.
+- **COMMENTS**: *why* not *what*. No commented-out code committed.
+- **IMPORTS**: stdlib → third-party → internal. No unused/wildcard.
+- **MAGIC VALUES**: no bare literals → named constants.
+- **DEAD CODE**: remove. No unreachable/unused.
+- **DRY + YAGNI**: no repeat, no over-abstract. Extract on real duplication only.
+
+## 11. Self-Improving Structure
+Lay out capabilities so behavior inspectable, testable, safely self-correcting.
+- **Capsule**: one behavior = prompt+schema+contract+policy+handler+eval colocated. Edit/delete one place, no file-hop. Cohesion > premature split (§10).
+- **Self-describing**: typed in/out + permission rule beside code; self-registers, no central registry.
+- **Self-testing**: ships its eval. Bug → permanent regression test. Golden suite proves real gain.
+- **Self-correcting**: never silent-mutate — propose diff → test → snapshot → approval for risky (§5). Critique post-exec (`verify`); builder ≠ reviewer (`review`).
+- **Self-remembering**: log why + failure modes → no repeat; version behaviors; runtime failure = next task.
+
+---
+*Directives define intent. Orchestration reasons. Execution runs. Gather first. Solve once. Keep it simple.*

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@xynogen/pix-skills",
-	"version": "0.1.0",
-	"description": "Pi extension — agent skill loader (read_skill tool + skills bundle)",
+	"version": "0.2.0",
+	"description": "Pi extension — agent skill loader (skill tool + skills bundle)",
 	"type": "module",
 	"main": "src/index.ts",
 	"scripts": {
@@ -10,6 +10,7 @@
 	"files": [
 		"src",
 		"skills",
+		"AGENT.md",
 		"README.md",
 		"LICENSE"
 	],

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * pix-skills — skill loader extension
  *
- * Registers a `read_skill` tool that lets the agent load any bundled skill's
+ * Registers a `skill` tool that lets the agent load any bundled skill's
  * full SKILL.md (or flat .md) by name. This is the safe "agent prompts itself"
  * pattern: the agent calls the tool explicitly; no autonomous injection.
  *
@@ -10,6 +10,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -18,12 +19,17 @@ import { Type } from "typebox";
 
 // ─── Skill resolution ─────────────────────────────────────────────────────────
 
-/** Absolute path to this package's skills/ directory. */
+/** Absolute path to this package's bundled skills/ directory. */
 function skillsRoot(): string {
 	const here = fileURLToPath(new URL(".", import.meta.url));
 	return resolve(here, "..", "skills");
 }
 
+/** Absolute path to the user-level skills directory (~/.pi/agent/skills). */
+function userSkillsRoot(): string {
+	return join(homedir(), ".pi", "agent", "skills");
+}
+
 interface SkillEntry {
 	name: string;
 	/** Absolute path to the SKILL.md or flat .md file. */
@@ -31,13 +37,12 @@ interface SkillEntry {
 }
 
 /**
- * Discover all skills from the package's skills/ directory.
+ * Scan a single skills root directory.
  * Supports two layouts:
  *   - flat:     skills/commit.md
  *   - subdir:   skills/commit/SKILL.md
  */
-function discoverSkills(): SkillEntry[] {
-	const root = skillsRoot();
+function scanSkillsDir(root: string): SkillEntry[] {
 	if (!existsSync(root)) return [];
 
 	const entries: SkillEntry[] = [];
@@ -56,7 +61,23 @@ function discoverSkills(): SkillEntry[] {
 		}
 	}
 
-	return entries.sort((a, b) => a.name.localeCompare(b.name));
+	return entries;
+}
+
+/**
+ * Discover all skills from bundled skills/ AND ~/.pi/agent/skills/.
+ * Bundled skills take precedence on name collision.
+ * Results sorted alphabetically by name.
+ */
+function discoverSkills(): SkillEntry[] {
+	const bundled = scanSkillsDir(skillsRoot());
+	const user = scanSkillsDir(userSkillsRoot());
+
+	// Merge: bundled wins on collision
+	const seen = new Set(bundled.map((s) => s.name));
+	const merged = [...bundled, ...user.filter((s) => !seen.has(s.name))];
+
+	return merged.sort((a, b) => a.name.localeCompare(b.name));
 }
 
 /** Extract the `description` from YAML frontmatter, or null. */
@@ -87,16 +108,16 @@ const ParamsSchema = Type.Object({
 
 export default function registerSkillLoader(pi: ExtensionAPI): void {
 	pi.registerTool({
-		name: "read_skill",
+		name: "skill",
 		label: "Read Skill",
 		description:
 			"Browse and load bundled skills. No args → list all skills with descriptions. name only → description for that skill. name + full=true → full instructions.",
 		promptSnippet: "Browse and load bundled skill instructions",
 		promptGuidelines: [
-			"Call read_skill() with no arguments to list all available skills and their descriptions.",
-			"Call read_skill(name=<skill>) to read the description of a specific skill before deciding to load it.",
-			"Call read_skill(name=<skill>, full=true) to load the full procedure for a skill before executing it.",
-			"Prefer read_skill over the read tool for skills — it resolves the correct path regardless of install location.",
+			"Call skill() with no arguments to list all available skills and their descriptions.",
+			"Call skill(name=<skill>) to read the description of a specific skill before deciding to load it.",
+			"Call skill(name=<skill>, full=true) to load the full procedure for a skill before executing it.",
+			"Prefer skill() over the read tool for skills — it resolves the correct path regardless of install location.",
 		],
 		executionMode: "sequential",
 		parameters: ParamsSchema,
@@ -173,7 +194,7 @@ export default function registerSkillLoader(pi: ExtensionAPI): void {
 			const { name, full } = args as { name?: string; full?: boolean };
 			const label = name ? `${name}${full ? " (full)" : ""}` : "list";
 			return new Text(
-				`${theme.fg("toolTitle", theme.bold("read_skill"))} ${theme.fg("muted", label)}`,
+				`${theme.fg("toolTitle", theme.bold("skill"))} ${theme.fg("muted", label)}`,
 				0,
 				0,
 			);