@caupulican/pi-adaptative 0.81.42 → 0.84.1

package/dist/bundled-resources/skills/secure-agent-tool-surfaces/references/defensive-exploit-catalogue.md

@@ -0,0 +1,175 @@
+# Defensive exploit catalogue for agent harnesses
+
+This is an awareness and regression catalogue, not a payload cookbook. Use
+inert fixtures and local test doubles. Active testing still requires the
+`authorized-web-security-audit` contract.
+
+For every class, identify the threatened invariant, enforcing owner, safe
+fixture, negative control, observable side effects, and cleanup. The regression
+oracle must assert host behavior, not merely model refusal text.
+
+## Agent and context attacks
+
+### Prompt and tool injection
+
+- **Vector:** user, repository, web, document, image metadata, tool description,
+  schema, result, error, or worker output contains instructions that conflict
+  with owner intent.
+- **Defense:** explicit trust labels, data/instruction separation, structured
+  bounded results, and capability enforcement outside the model.
+- **Regression oracle:** injected text cannot enable a denied tool, read a
+  protected resource, change policy, contact a new destination, or persist memory.
+
+### Tool poisoning, shadowing, and rug pulls
+
+- **Vector:** a server advertises a deceptive tool, impersonates another name,
+  changes description/schema after approval, or uses one tool's text to steer a
+  privileged tool.
+- **Defense:** provenance allowlist, namespace isolation, schema/manifest hash,
+  change re-approval, and per-tool capabilities.
+- **Regression oracle:** a changed or colliding identity is quarantined before
+  execution; previously approved authority is not inherited.
+
+### Goal, memory, and context poisoning
+
+- **Vector:** untrusted content becomes a durable goal, trusted fact, preference,
+  policy, compaction summary, or cross-session memory.
+- **Defense:** provenance-preserving memory types, human/host admission gates,
+  tenant keys, bounded retention, integrity/version checks, and reversible history.
+- **Regression oracle:** untrusted data remains query data and cannot alter a
+  future session's authority or system instructions.
+
+### Excessive agency and confused deputy
+
+- **Vector:** a low-trust caller induces a privileged agent/server to exercise
+  credentials or scopes the caller does not possess.
+- **Defense:** principal-bound capabilities, per-client consent, audience/scope
+  validation, no token passthrough, progressive elevation, and human approval at
+  high-impact edges.
+- **Regression oracle:** the same intent from an unapproved principal is denied
+  without side effects or information leakage.
+
+## Tool input and interpreter attacks
+
+### Command and argument injection
+
+- **Vector:** model text crosses into shell syntax, option parsing, environment
+  expansion, nested interpreters, or executable selection.
+- **Defense:** direct executable/argv adapters, option terminators, allowlisted
+  grammar, clean environment, canonical cwd, and process sandbox.
+- **Regression oracle:** metacharacters and option-shaped filenames remain data;
+  only the intended executable and arguments are observed by a fake process.
+
+### Path traversal, symlink, and archive escape
+
+- **Vector:** relative traversal, mixed separators, device/UNC paths, alternate
+  streams, case/Unicode aliases, symlink swaps, or archive entries escape a root.
+- **Defense:** platform-aware canonicalization, handle-relative/symlink-safe open,
+  post-open verification, exact extraction root, and denied sensitive paths.
+- **Regression oracle:** aliases and a deterministic symlink swap cannot read or
+  mutate outside the capability root.
+
+### Unsafe parsing and deserialization
+
+- **Vector:** duplicate keys, prototype pollution, accessors, unsafe integers,
+  deep nesting, trailing values, decompression bombs, or executable formats.
+- **Defense:** strict schemas, null-prototype/owned-property access, depth/byte
+  bounds, non-executable formats, and fail-closed parse errors.
+- **Regression oracle:** malicious shapes are rejected before state change while
+  a structurally similar valid negative control succeeds.
+
+### Query and template injection
+
+- **Vector:** untrusted values become query language, regex, glob, selector,
+  template, markup, or code rather than parameters.
+- **Defense:** typed AST/builders, parameter binding, safe regex/glob limits,
+  output encoding, and no dynamic evaluation.
+- **Regression oracle:** metacharacters cannot alter query/operator structure or
+  cross the intended record/resource set.
+
+## Network and transport attacks
+
+### SSRF, redirect escape, and DNS rebinding
+
+- **Vector:** a permitted URL resolves or redirects to private, loopback,
+  link-local, metadata, or another tenant's service; DNS changes after validation.
+- **Defense:** standard URL/IP parsing, scheme/host/port/address allowlists,
+  redirect-hop checks, DNS pinning/revalidation, egress proxy/policy, and stripped
+  cross-origin credentials.
+- **Regression oracle:** safe initial DNS followed by a forbidden result, and an
+  external redirect to loopback, both fail before connection.
+
+### MCP session hijack and event injection
+
+- **Vector:** guessed/stolen session ids, unauthenticated HTTP, cross-node queues,
+  resumed streams, or tool-list notifications cross principals or streams.
+- **Defense:** authentication on every request, Origin validation, random ids
+  bound to principal, per-stream event ids, generation fences, and scoped queues.
+- **Regression oracle:** another authenticated user with the session id cannot
+  call, resume, cancel, enumerate, or receive the owner's work.
+
+### Token substitution and passthrough
+
+- **Vector:** a server accepts a token issued to another resource or forwards the
+  inbound bearer token to a downstream service.
+- **Defense:** issuer/audience/expiry/scope validation and distinct downstream
+  credentials bound to the server's own client role.
+- **Regression oracle:** a valid wrong-audience token and a broader-than-required
+  token are rejected without downstream contact.
+
+## State, concurrency, and availability attacks
+
+### Tenant crossover
+
+- **Vector:** caches, workers, shells, memory, files, task ids, notifications, or
+  credentials are keyed only by cwd, process, model, or guessable id.
+- **Defense:** session tenant plus trusted principal on every key and transition;
+  non-enumerating denials and tenant-specific cleanup.
+- **Regression oracle:** two simultaneous sessions in one workspace cannot see,
+  mutate, cancel, resume, or receive each other's state.
+
+### Replay, stale result, and race exploitation
+
+- **Vector:** duplicate delivery, ambiguous retry, out-of-order completion,
+  check/use gaps, stale worker generation, or concurrent mutation repeats effects.
+- **Defense:** intent-bound idempotency, versions/generation fencing, atomic
+  transitions, durable terminal records, and postcondition reconciliation.
+- **Regression oracle:** barriers force each ordering; the invariant is either
+  fully committed once or absent, never partially or twice.
+
+### Resource exhaustion and denial of wallet
+
+- **Vector:** recursive delegation, tool loops, oversized results, decompression,
+  regex backtracking, unbounded fan-out/retries, hung children, or cost amplification.
+- **Defense:** independent token/cost/time/CPU/memory/output/depth/fan-out budgets,
+  cancellation, circuit breakers, backpressure, and bounded summaries.
+- **Regression oracle:** the smallest exceeded budget terminates owned work,
+  emits one terminal status, and leaves no live descendants or unbounded artifact.
+
+### Secret exfiltration through legitimate channels
+
+- **Vector:** prompt injection places secrets in search queries, URLs, issue/email
+  bodies, logs, errors, telemetry, filenames, or worker results.
+- **Defense:** model-blind secret handles, sink-aware redaction/DLP, destination
+  capabilities, explicit external-mutation approval, and minimum data projection.
+- **Regression oracle:** canary secrets never appear in model context, artifacts,
+  logs, argv, URLs, or outbound fake-service captures.
+
+## Supply-chain and local-server attacks
+
+### Malicious server, plugin, skill, or dependency
+
+- **Vector:** installation executes lifecycle code, configuration embeds a
+  startup command, bundled instructions expand authority, or an update changes
+  behavior after trust was granted.
+- **Defense:** exact pins and hashes, provenance/license review, no install scripts
+  by default, displayed commands, sandboxing, signed/verified updates, and
+  re-approval on manifest/capability changes.
+- **Regression oracle:** an altered artifact or capability manifest is rejected
+  before execution and cannot inherit stored credentials or approvals.
+
+## Review outcome
+
+Classify every tested item as confirmed, rejected with the negative-control
+reason, incomplete with the missing probe, or residual architectural risk. Do
+not call the harness secure merely because this catalogue has coverage.

package/dist/bundled-resources/skills/secure-agent-tool-surfaces/references/tool-boundary-checklist.md

@@ -0,0 +1,87 @@
+# Tool boundary checklist
+
+Use this checklist for a new or materially changed agent tool, MCP surface,
+extension, connector, background worker, or memory adapter.
+
+## Contract
+
+- Name the authoritative owner and versioned input/output schema.
+- Classify the operation: read-only, local mutation, external mutation,
+  destructive, credential-bearing, or authority-changing.
+- Identify the trusted principal and session tenant from a host-owned channel.
+- Compute effective authority as an intersection; textual inputs can only narrow.
+- Bind approval to operation intent, canonical resources, schema/tool identity,
+  and expiry. Re-approve after material changes.
+- Define exact size, count, depth, fan-out, retry, time, cost, and concurrency limits.
+
+## Inputs and canonicalization
+
+- Parse once with a standard parser; reject ambiguity and trailing data.
+- Reject or deliberately handle unknown fields, duplicate keys, unsafe numbers,
+  prototype keys, accessors, invalid Unicode, alternate encodings, and bombs.
+- Canonicalize paths/URLs before policy, then validate the opened file or actual
+  connection again to close symlink, redirect, and DNS TOCTOU gaps.
+- Keep credentials out of user-controlled URLs, headers, command lines, and logs.
+
+## Effects
+
+- Filesystem: root capability, symlink-safe open, no auth/state/cross-tenant paths.
+- Process: direct argv where possible, bounded shell grammar otherwise, clean
+  environment, working-directory scope, process-tree cancellation.
+- Network: approved schemes/hosts/ports/IPs, redirect and DNS revalidation,
+  private/loopback/link-local/metadata denial, egress enforcement.
+- Storage: tenant key, atomicity, idempotency, replay fence, encryption and
+  retention appropriate to sensitivity.
+- External mutation: explicit confirmation, idempotency key bound to intent,
+  postcondition check, and ambiguity-safe retry behavior.
+
+## Results and composition
+
+- Validate result schema and encoded byte bound before model ingestion.
+- Preserve trust label, source, tenant, timestamp, and artifact digest.
+- Redact secrets from normal results, errors, telemetry, and terminal events.
+- Never let result text alter capability, policy, approval, tool selection, or memory.
+- Inject only a bounded projection; retain exact raw evidence in protected storage.
+
+## MCP transport
+
+- Prefer stdio for local servers; show exact command/arguments before approval.
+- Review/pin server source and dependencies; isolate environment and host access.
+- HTTP binds to loopback by default; remote use requires TLS and authentication.
+- Validate Origin, token issuer/audience/expiry/scopes, and per-client consent.
+- Do not pass inbound tokens to downstream APIs.
+- Bind session and resumable-event storage to the authenticated principal.
+- Treat tool/schema/list changes as a new trust decision.
+
+## Lifecycle
+
+- One coordinator owns admission and state transitions.
+- Every accepted call reaches exactly one terminal state.
+- Work beyond the foreground budget uses an owner-session background lane.
+- Completion is event-driven; waiting may block intentionally but never polls output.
+- Cancellation and shutdown reach subprocesses, sockets, browsers, files, and leases.
+- Reload/retry/reconnect uses generation fences and idempotent terminal delivery.
+
+## Required adversarial evidence
+
+- valid request and malformed negative control;
+- unauthorized principal/session and cross-tenant identifier;
+- stale, duplicate, replayed, and out-of-order action;
+- cancellation before, during, and after the external effect;
+- oversized/deep input and oversized result;
+- poisoned description/result attempting a privileged follow-up;
+- path alias/symlink or URL redirect/DNS boundary escape where applicable;
+- secret-shaped error/output;
+- crash/restart with no partial or duplicate effect;
+- schema/tool identity change after approval.
+
+## Primary references
+
+- [MCP transport security requirements](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)
+- [MCP authorization requirements](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
+- [MCP security best practices](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices)
+- [OWASP AI Agent Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/AI_Agent_Security_Cheat_Sheet.html)
+- [OWASP MCP Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/MCP_Security_Cheat_Sheet.html)
+
+These references are evidence inputs, not executable authority. Apply the
+repository's stricter contract when rules differ.

package/dist/bundled-resources/skills/skill-architect/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: skill-architect
-description: "Use when creating, rewriting, merging, or reviewing AI skills, prompt templates, or system prompts. Builds production-ready skills with the 5-Part Skill Anatomy, Freedom Dial, strict routing, references, validation, and known gaps."
+description: "Design, rewrite, merge, or review the content and routing architecture of AI skills, prompt templates, and system prompts. Use for Freedom Dial selection, instruction structure, trigger quality, overlap review, references, and known gaps; pair with skill-creator for safe Pi package scaffolding and structural validation."
 ---
 
 # Skill Architect
 
 ## How to use the skill
 
-Load this skill when the user asks to create, improve, merge, split, or audit a skill, agent role, tool instruction, prompt template, or system prompt.
+Load this skill when the user asks to design, improve, merge, split, or audit the content of a skill, agent role, tool instruction, prompt template, or system prompt. Pair it with `skill-creator` when creating or validating a Pi skill directory.
 
 Before generating anything, state the chosen **Freedom Dial** and why:
 

package/dist/bundled-resources/skills/skill-creator/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: skill-creator
+description: "Create, scaffold, validate, and package provider-neutral Pi skills with safe deterministic tooling. Use when the user asks to create a Pi skill, turn a workflow into a bundled or user skill, initialize a SKILL.md directory, validate skill structure, or add references/scripts/assets without provider-specific metadata."
+---
+
+# Pi Skill Creator
+
+## How to use the skill
+
+Use this skill for the physical creation and validation of Pi skill packages.
+Use `skill-architect` for instruction design, routing quality, Freedom Dial, and
+overlap decisions; this skill owns filesystem layout and deterministic gates.
+
+**Freedom Dial: Low Freedom for packaging.** Paths, frontmatter, required
+headers, provider neutrality, non-overwrite behavior, and validation have one
+correct contract. Skill content may use the Freedom Dial selected by
+`skill-architect`.
+
+Create a new skill with:
+
+```bash
+node <this-skill-directory>/scripts/init-skill.mjs <skill-name> --path <skills-directory> --resources references,scripts
+```
+
+Validate it with:
+
+```bash
+node <this-skill-directory>/scripts/validate-skill.mjs <skill-directory>
+```
+
+Read [references/pi-skill-contract.md](references/pi-skill-contract.md) before
+changing discovery, packaging, or validation rules.
+
+## North Star
+
+Produce one narrow, discoverable, provider-neutral Pi skill whose package is
+safe to create, complete enough to route correctly, bounded in context cost,
+and validated by executable checks without overwriting user work.
+
+Think before writing, reuse or refine an existing owner when possible, keep the
+change surgical, define a testable user outcome, and leave credentials,
+destructive changes, publication, and authority expansion to explicit human
+approval.
+
+## Core Sections
+
+### 1. Audit ownership first
+
+Search bundled, user, project, plugin, and configured skill roots by name,
+description, triggers, and semantic responsibility. Do not create a near-duplicate
+skill to avoid editing the existing owner.
+
+Choose one outcome:
+
+- refine the existing skill;
+- split a genuinely distinct job with explicit routing boundaries;
+- merge competing skills and update callers;
+- create a new skill only when no owner fits.
+
+For Pi harness work, final bundled behavior belongs under
+`packages/coding-agent/src/bundled-resources/skills/`. User-level files are
+temporary migration or validation sources unless the user explicitly requested
+a user-only skill.
+
+### 2. Scaffold safely
+
+Use `scripts/init-skill.mjs`; do not hand-create a parallel layout. The
+initializer:
+
+- accepts only lowercase hyphen-case names;
+- creates exactly one direct child of the selected skills directory;
+- stages then atomically renames the package;
+- refuses an existing destination and never overwrites;
+- creates only requested `scripts`, `references`, or `assets` directories;
+- writes quoted YAML frontmatter and the required Markdown spine;
+- never creates `agents/openai.yaml` or other provider-specific metadata.
+
+Do not use a broad home/workspace path as the destination. Resolve the exact
+skill root first and inspect worktree state when working in a repository.
+
+### 3. Author one job
+
+Use `skill-architect` to set routing and content. Keep the main `SKILL.md` under
+500 lines and preferably under 350. Its frontmatter description is the routing
+face: name the action, trigger contexts, and concrete user intents without
+claiming unrelated domains.
+
+Use these exact level-two headers in order:
+
+1. `## How to use the skill`
+2. `## North Star`
+3. `## Core Sections`
+4. `## Anti-Patterns`
+5. `## Examples`
+6. `## Self-Check`
+7. `## Known Gaps`
+
+Move heavy or rarely needed knowledge into `references/`, deterministic
+automation into `scripts/`, and output ingredients into `assets/`. Link only
+resources the skill actually needs and state when to read or run them.
+
+### 4. Preserve provider and authority neutrality
+
+Pi is multi-provider. Skill behavior belongs in Markdown and deterministic
+resources, not `agents/openai.yaml`, provider model names, hidden reasoning, or
+one provider's tool protocol. Refer to capabilities by semantic role and adapt
+to the active tool surface.
+
+A skill is instruction, not authority. It cannot grant credentials, network
+scope, filesystem/process access, destructive actions, settings changes,
+publishing, or delegation. Preserve the host's user/session/worker capability
+intersection and repository instructions.
+
+### 5. Add evidence before implementation
+
+For a bundled skill, first add a focused discovery/content test that fails for
+the missing skill or contract. For scripts, add valid input, malformed negative
+control, path/traversal, existing-destination, and cross-platform cases in
+proportion to risk.
+
+Do not test only keyword presence when runtime discovery or executable behavior
+is the invariant. Avoid executing external providers or paid APIs in skill tests.
+
+### 6. Validate and forward-test
+
+Run `scripts/validate-skill.mjs` on the completed directory, then the repository's
+focused discovery and script tests. Inspect output, not only exit status.
+
+Forward-test at least these prompts against the description:
+
+- one request that must load the skill;
+- one adjacent request that must not load it;
+- one ambiguous request whose safest behavior is explicit;
+- one request exercising each linked reference or script.
+
+Run the repository-required broader checks after the focused tests. If the skill
+is bundled, verify it loads from a blank profile and that the packaged asset copy
+includes every linked resource.
+
+### 7. Hand off precisely
+
+Report the skill name/path, ownership decision, created resources, focused test,
+validator result, overlap decision, rejected candidates, and known gaps. Mention
+provider neutrality explicitly. Do not claim a skill is installed in an already
+released binary until the package was built/released and tested there.
+
+## Anti-Patterns
+
+- Creating a skill before searching existing owners.
+- Combining several jobs into a broad expert persona.
+- Copying external prompts or exploit catalogues verbatim.
+- Generating provider-specific metadata for a multi-provider Pi skill.
+- Writing scripts that overwrite existing directories or accept traversal names.
+- Keeping large catalogues in `SKILL.md` when a reference is more selective.
+- Treating a valid frontmatter parse as proof of useful routing or behavior.
+- Claiming bundled source is already installed in a released executable.
+
+## Examples
+
+**New narrow workflow:** no existing skill owns authorized web assessment.
+Scaffold `authorized-web-security-audit`, write a focused discovery test, keep
+the assessment contract in `references/`, validate, and forward-test an
+authorized and an unauthorized prompt.
+
+**Overlap found:** a requested "prompt writer" duplicates `skill-architect`.
+Refine that owner instead of creating `prompt-writer`.
+
+**Unsafe name:** `../security` or `Security Review` is rejected by the
+initializer. Choose `security-review`; never normalize traversal into a path.
+
+## Self-Check
+
+- Existing skill roots were searched for name and semantic overlap.
+- The skill has one job and a discriminating quoted description.
+- The initializer created one direct child and overwrote nothing.
+- No provider-specific metadata exists.
+- Required headers are present in order and `SKILL.md` is under 500 lines.
+- Every linked resource exists and has an explicit load/run trigger.
+- Discovery, executable negative controls, validator, and forward-routing tests pass.
+- Bundled versus installed/released status is reported accurately.
+
+## Known Gaps
+
+- Structural validation cannot prove domain correctness or routing quality.
+- The initializer does not install, publish, or enable a skill in a running
+  process; reload/restart and package/release steps remain separate.
+- Existing third-party skill formats may need a reviewed Pi-native migration
+  instead of direct scaffolding.

package/dist/bundled-resources/skills/skill-creator/references/pi-skill-contract.md

@@ -0,0 +1,73 @@
+# Pi skill package contract
+
+## Required layout
+
+```text
+<skill-name>/
+  SKILL.md
+  scripts/       optional deterministic automation
+  references/    optional selectively loaded knowledge
+  assets/        optional output ingredients
+```
+
+The directory name and frontmatter `name` are the same lowercase hyphen-case
+identifier. Pi bundled skills are provider-neutral; do not add an `agents/`
+directory or `openai.yaml`.
+
+## Required frontmatter
+
+```yaml
+---
+name: narrow-skill-name
+description: "What it does and the concrete requests or contexts that load it."
+---
+```
+
+Use one `name` and one quoted, non-empty `description`. Keep the description
+under 1,000 characters and focused enough that adjacent skills do not route.
+
+## Required spine
+
+Use these headers once and in order:
+
+1. `## How to use the skill`
+2. `## North Star`
+3. `## Core Sections`
+4. `## Anti-Patterns`
+5. `## Examples`
+6. `## Self-Check`
+7. `## Known Gaps`
+
+The main file must be under 500 lines. Prefer references over a large main file,
+but do not create empty documentation merely to satisfy a layout convention.
+
+## Resource rules
+
+- Reference links are relative to the skill directory and must not escape it.
+- `scripts/` must be deterministic, bounded, non-destructive by default, and
+  portable across supported platforms or explicit about its platform.
+- `assets/` are copied/read as data; never hide executable instructions there.
+- Do not duplicate the same rule across the main file and references. The main
+  file routes to the authoritative detail.
+- Do not embed credentials, host-specific paths, provider tokens, or generated
+  runtime state.
+
+## Validation layers
+
+1. `validate-skill.mjs`: package shape, safe name, quoted frontmatter, line
+   bound, required header order, provider neutrality, and linked-resource paths.
+2. Discovery test: a blank Pi profile finds the bundled skill and its source
+   scope is correct.
+3. Content contract: the critical behavior and linked resources are present.
+4. Script tests: success, malformed input, traversal, collision, and platform
+   behavior.
+5. Forward routing: positive, adjacent negative, and ambiguous prompts.
+6. Package smoke: built/released Pi includes and loads the resources.
+
+## Ownership boundary
+
+`skill-creator` owns package creation and structural validation.
+`skill-architect` owns instruction architecture and content quality.
+`pi-harness-learning` decides whether a recurring lesson belongs in memory,
+skill, prompt, extension, or core source. `deduplicate-by-evidence` resolves
+overlap between competing skills.

package/dist/bundled-resources/skills/skill-creator/scripts/init-skill.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ALLOWED_RESOURCES = new Set(["assets", "references", "scripts"]);
+
+function fail(message) {
+	console.error(`Error: ${message}`);
+	process.exitCode = 1;
+}
+
+function parseArguments(argv) {
+	const [name, ...rest] = argv;
+	let outputPath;
+	let description;
+	let resources = [];
+
+	for (let index = 0; index < rest.length; index++) {
+		const option = rest[index];
+		const value = rest[index + 1];
+		if (option === "--path" || option === "--description" || option === "--resources") {
+			if (!value || value.startsWith("--")) throw new Error(`${option} requires a value`);
+			index++;
+			if (option === "--path") outputPath = value;
+			if (option === "--description") description = value;
+			if (option === "--resources") resources = value.split(",").filter(Boolean);
+			continue;
+		}
+
+		throw new Error(`unknown option: ${option}`);
+	}
+
+	return { name, outputPath, description, resources };
+}
+
+function titleFromName(name) {
+	return name
+		.split("-")
+		.map((part) => part[0].toUpperCase() + part.slice(1))
+		.join(" ");
+}
+
+function renderSkill(name, description) {
+	const title = titleFromName(name);
+	const routedDescription =
+		description ?? `Use when working on ${title} tasks that need a reusable, evidence-gated Pi workflow.`;
+
+	return `---
+name: ${name}
+description: ${JSON.stringify(routedDescription)}
+---
+
+# ${title}
+
+## How to use the skill
+
+State when this skill applies, choose its mode or Freedom Dial, and name any
+references or scripts that must be loaded before acting.
+
+## North Star
+
+Define the observable outcome, ownership boundary, and human approval edges.
+
+## Core Sections
+
+### 1. Establish the contract
+
+Describe the smallest evidence-backed workflow and its required inputs.
+
+### 2. Execute and verify
+
+Describe the implementation loop, negative controls, and completion gate.
+
+## Anti-Patterns
+
+- List the shortcuts or boundary violations this skill must prevent.
+
+## Examples
+
+Provide one positive routing example and one adjacent negative example.
+
+## Self-Check
+
+- The requested outcome and validation evidence are explicit.
+
+## Known Gaps
+
+- Record what this skill cannot prove or perform.
+`;
+}
+
+let parsed;
+try {
+	parsed = parseArguments(process.argv.slice(2));
+} catch (error) {
+	fail(error instanceof Error ? error.message : String(error));
+}
+
+if (parsed) {
+	const { name, outputPath, description, resources } = parsed;
+	if (!name || !NAME_PATTERN.test(name) || name.length > 64) {
+		fail("skill name must be 1-64 lowercase alphanumeric characters separated by single hyphens");
+	} else if (!outputPath) {
+		fail("--path is required");
+	} else if (description !== undefined && (description.trim().length === 0 || description.length > 1000)) {
+		fail("--description must contain 1-1000 characters");
+	} else {
+		const invalidResource = resources.find((resource) => !ALLOWED_RESOURCES.has(resource));
+		if (invalidResource) {
+			fail(`unsupported resource directory: ${invalidResource}`);
+		} else {
+			const parent = resolve(outputPath);
+			mkdirSync(parent, { recursive: true });
+			const canonicalParent = realpathSync(parent);
+			const destination = join(canonicalParent, name);
+			if (existsSync(destination)) {
+				fail(`destination already exists: ${destination}`);
+			} else {
+				const stage = join(canonicalParent, `.pi-skill-${process.pid}-${randomUUID()}`);
+				try {
+					mkdirSync(stage, { mode: 0o700 });
+					writeFileSync(join(stage, "SKILL.md"), renderSkill(name, description), {
+						encoding: "utf8",
+						flag: "wx",
+						mode: 0o600,
+					});
+					for (const resource of [...new Set(resources)].sort()) {
+						mkdirSync(join(stage, resource), { mode: 0o700 });
+					}
+					renameSync(stage, destination);
+					console.log(`Created provider-neutral Pi skill: ${destination}`);
+				} catch (error) {
+					rmSync(stage, { recursive: true, force: true });
+					fail(error instanceof Error ? error.message : String(error));
+				}
+			}
+		}
+	}
+}