@preapexis/piexis 0.1.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/.github/workflows/publish.yml +35 -0
  2. package/AGENTS.md +21 -41
  3. package/README.md +75 -142
  4. package/extensions/agents.ts +205 -0
  5. package/extensions/ask-question.ts +54 -95
  6. package/extensions/recommended-tools.ts +62 -0
  7. package/extensions/ui.ts +204 -58
  8. package/lib/agent-config.ts +55 -0
  9. package/lib/agents.ts +208 -0
  10. package/lib/question-model.ts +98 -0
  11. package/lib/question-ui.ts +214 -0
  12. package/lib/recommended-tools.ts +119 -0
  13. package/lib/subagent-runner.ts +146 -0
  14. package/lib/ui-tips.json +41 -0
  15. package/package.json +9 -12
  16. package/prompts/init.md +10 -2
  17. package/prompts/summary.md +7 -6
  18. package/schemas/agent.schema.json +48 -0
  19. package/scripts/release.mjs +32 -0
  20. package/skills/{claude-api/LICENSE.txt → caveman/LICENSE} +2 -2
  21. package/skills/caveman/LICENSE-MIT +21 -0
  22. package/skills/caveman/NOTICE +10 -0
  23. package/skills/caveman/SKILL.md +89 -0
  24. package/skills/find-skills/SKILL.md +141 -0
  25. package/skills/ponytail/LICENSE +21 -0
  26. package/skills/ponytail/NOTICE +9 -0
  27. package/skills/ponytail/SKILL.md +52 -0
  28. package/skills-lock.json +6 -0
  29. package/tests/agents.test.mjs +605 -0
  30. package/tests/ask-question-pty.test.mjs +16 -0
  31. package/tests/ask-question.test.mjs +269 -0
  32. package/tests/fixtures/agents-provider.ts +55 -0
  33. package/tests/fixtures/ask-question-pty.py +91 -0
  34. package/tests/fixtures/ask-question-terminal.mjs +69 -0
  35. package/tests/fixtures/recommended-tools-terminal.mjs +103 -0
  36. package/tests/init-workflow.test.mjs +31 -0
  37. package/tests/recommended-tools-pty.test.mjs +16 -0
  38. package/tests/recommended-tools.test.mjs +423 -0
  39. package/tests/resources.test.mjs +66 -0
  40. package/tests/skills-routing.test.mjs +7 -4
  41. package/tests/ui-tip-reload.test.mjs +70 -0
  42. package/tests/ui.test.mjs +450 -0
  43. package/tsconfig.json +1 -0
  44. package/.github/workflows/npm-publish.yml +0 -63
  45. package/PERMISSION_MODES_PLAN.md +0 -279
  46. package/WHAT_YOU_GET.md +0 -153
  47. package/eval/README.md +0 -72
  48. package/eval/permission-cases.json +0 -28
  49. package/eval/permissions.mjs +0 -103
  50. package/extensions/background-tasks.ts +0 -433
  51. package/extensions/background-worker.ts +0 -50
  52. package/extensions/glob.ts +0 -32
  53. package/extensions/mode.ts +0 -397
  54. package/lib/bash-approvals.ts +0 -113
  55. package/lib/bash-policy.ts +0 -164
  56. package/lib/mode-policy.ts +0 -174
  57. package/lib/path-policy.ts +0 -182
  58. package/lib/permission-classifier.ts +0 -128
  59. package/lib/permission-config.ts +0 -91
  60. package/lib/permission-denials.ts +0 -32
  61. package/lib/permission-intent.ts +0 -128
  62. package/lib/permission-taxonomy.ts +0 -15
  63. package/lib/task-broker.ts +0 -65
  64. package/lib/task-checkout.ts +0 -39
  65. package/lib/task-git.ts +0 -44
  66. package/lib/task-patch.ts +0 -106
  67. package/lib/task-permissions.ts +0 -51
  68. package/lib/task-report.ts +0 -62
  69. package/lib/task-worktree-policy.ts +0 -56
  70. package/skills/claude-api/SKILL.md +0 -572
  71. package/skills/claude-api/csharp/claude-api/README.md +0 -362
  72. package/skills/claude-api/csharp/claude-api/batches.md +0 -14
  73. package/skills/claude-api/csharp/claude-api/files-api.md +0 -25
  74. package/skills/claude-api/csharp/claude-api/streaming.md +0 -28
  75. package/skills/claude-api/csharp/claude-api/tool-use.md +0 -164
  76. package/skills/claude-api/curl/examples.md +0 -256
  77. package/skills/claude-api/curl/managed-agents.md +0 -371
  78. package/skills/claude-api/go/claude-api/README.md +0 -188
  79. package/skills/claude-api/go/claude-api/files-api.md +0 -23
  80. package/skills/claude-api/go/claude-api/streaming.md +0 -43
  81. package/skills/claude-api/go/claude-api/tool-use.md +0 -220
  82. package/skills/claude-api/go/managed-agents/README.md +0 -564
  83. package/skills/claude-api/java/claude-api/README.md +0 -238
  84. package/skills/claude-api/java/claude-api/files-api.md +0 -27
  85. package/skills/claude-api/java/claude-api/streaming.md +0 -24
  86. package/skills/claude-api/java/claude-api/tool-use.md +0 -228
  87. package/skills/claude-api/java/managed-agents/README.md +0 -443
  88. package/skills/claude-api/php/claude-api/README.md +0 -174
  89. package/skills/claude-api/php/claude-api/batches.md +0 -15
  90. package/skills/claude-api/php/claude-api/files-api.md +0 -13
  91. package/skills/claude-api/php/claude-api/streaming.md +0 -27
  92. package/skills/claude-api/php/claude-api/tool-use.md +0 -253
  93. package/skills/claude-api/php/managed-agents/README.md +0 -443
  94. package/skills/claude-api/python/claude-api/README.md +0 -565
  95. package/skills/claude-api/python/claude-api/batches.md +0 -198
  96. package/skills/claude-api/python/claude-api/files-api.md +0 -170
  97. package/skills/claude-api/python/claude-api/sdk-upgrade.md +0 -286
  98. package/skills/claude-api/python/claude-api/streaming.md +0 -179
  99. package/skills/claude-api/python/claude-api/tool-use.md +0 -627
  100. package/skills/claude-api/python/managed-agents/README.md +0 -335
  101. package/skills/claude-api/ruby/claude-api/README.md +0 -134
  102. package/skills/claude-api/ruby/claude-api/streaming.md +0 -16
  103. package/skills/claude-api/ruby/claude-api/tool-use.md +0 -41
  104. package/skills/claude-api/ruby/managed-agents/README.md +0 -394
  105. package/skills/claude-api/shared/admin-api.md +0 -179
  106. package/skills/claude-api/shared/agent-design.md +0 -101
  107. package/skills/claude-api/shared/anthropic-cli.md +0 -269
  108. package/skills/claude-api/shared/claude-platform-on-aws.md +0 -59
  109. package/skills/claude-api/shared/cost-optimization.md +0 -233
  110. package/skills/claude-api/shared/error-codes.md +0 -262
  111. package/skills/claude-api/shared/live-sources.md +0 -166
  112. package/skills/claude-api/shared/managed-agents-api-reference.md +0 -455
  113. package/skills/claude-api/shared/managed-agents-client-patterns.md +0 -220
  114. package/skills/claude-api/shared/managed-agents-core.md +0 -359
  115. package/skills/claude-api/shared/managed-agents-environments.md +0 -226
  116. package/skills/claude-api/shared/managed-agents-events.md +0 -290
  117. package/skills/claude-api/shared/managed-agents-memory.md +0 -201
  118. package/skills/claude-api/shared/managed-agents-multiagent.md +0 -260
  119. package/skills/claude-api/shared/managed-agents-onboarding.md +0 -82
  120. package/skills/claude-api/shared/managed-agents-outcomes.md +0 -108
  121. package/skills/claude-api/shared/managed-agents-overview.md +0 -77
  122. package/skills/claude-api/shared/managed-agents-scheduled-deployments.md +0 -156
  123. package/skills/claude-api/shared/managed-agents-self-hosted-sandboxes.md +0 -282
  124. package/skills/claude-api/shared/managed-agents-tools.md +0 -504
  125. package/skills/claude-api/shared/managed-agents-webhooks.md +0 -143
  126. package/skills/claude-api/shared/model-migration.md +0 -1872
  127. package/skills/claude-api/shared/models.md +0 -142
  128. package/skills/claude-api/shared/platform-availability.md +0 -53
  129. package/skills/claude-api/shared/prompt-audit.md +0 -223
  130. package/skills/claude-api/shared/prompt-caching.md +0 -292
  131. package/skills/claude-api/shared/token-counting.md +0 -56
  132. package/skills/claude-api/shared/tool-use-concepts.md +0 -526
  133. package/skills/claude-api/typescript/claude-api/README.md +0 -405
  134. package/skills/claude-api/typescript/claude-api/batches.md +0 -106
  135. package/skills/claude-api/typescript/claude-api/files-api.md +0 -98
  136. package/skills/claude-api/typescript/claude-api/streaming.md +0 -178
  137. package/skills/claude-api/typescript/claude-api/tool-use.md +0 -586
  138. package/skills/claude-api/typescript/managed-agents/README.md +0 -359
  139. package/tests/auto-permissions.test.mjs +0 -315
  140. package/tests/background-tasks.test.mjs +0 -27
  141. package/tests/background-worker.test.mjs +0 -60
  142. package/tests/bash-permissions.test.mjs +0 -276
  143. package/tests/glob.test.mjs +0 -31
  144. package/tests/mode.test.mjs +0 -62
  145. package/tests/permission-evaluation.test.mjs +0 -70
  146. package/tests/permission-foundation.test.mjs +0 -194
  147. package/tests/permission-policy.test.mjs +0 -158
  148. package/tests/runtime/README.md +0 -51
  149. package/tests/runtime/harness.mjs +0 -190
  150. package/tests/runtime/permissions.test.mjs +0 -192
  151. package/tests/runtime/tui.test.mjs +0 -60
  152. package/tests/task-integration.test.mjs +0 -324
  153. package/tests/task-permissions.test.mjs +0 -178
  154. package/tests/task-worktree-policy.test.mjs +0 -53
package/package.json CHANGED
@@ -1,8 +1,12 @@
1
1
  {
2
2
  "name": "@preapexis/piexis",
3
- "version": "0.1.2",
3
+ "version": "0.2.4",
4
4
  "type": "module",
5
5
  "description": "Extensions, skills, prompts, and themes for pi",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://github.com/VarunGaikwad/piexis"
9
+ },
6
10
  "keywords": [
7
11
  "pi-package"
8
12
  ],
@@ -17,18 +21,15 @@
17
21
  },
18
22
  "scripts": {
19
23
  "test": "node --test tests/*.test.mjs",
20
- "test:runtime": "node --test tests/runtime/*.test.mjs",
21
24
  "check": "tsc --noEmit",
22
- "eval:permissions": "node eval/permissions.mjs",
23
- "test:sandbox": "PIEXIS_REQUIRE_SANDBOX=1 node --test tests/mode-sandbox.test.mjs"
25
+ "release": "node scripts/release.mjs"
24
26
  },
25
27
  "pi": {
26
28
  "extensions": [
27
29
  "./extensions/ask-question.ts",
28
- "./extensions/background-tasks.ts",
29
- "./extensions/glob.ts",
30
- "./extensions/mode.ts",
31
- "./extensions/ui.ts"
30
+ "./extensions/ui.ts",
31
+ "./extensions/recommended-tools.ts",
32
+ "./extensions/agents.ts"
32
33
  ],
33
34
  "skills": [
34
35
  "./skills"
@@ -40,10 +41,6 @@
40
41
  "./themes"
41
42
  ]
42
43
  },
43
- "dependencies": {
44
- "@anthropic-ai/sandbox-runtime": "0.0.77",
45
- "jiti": "2.6.1"
46
- },
47
44
  "devDependencies": {
48
45
  "@types/node": "24.10.0",
49
46
  "typescript": "5.9.3"
package/prompts/init.md CHANGED
@@ -14,7 +14,7 @@ $ARGUMENTS
14
14
  - Target the current directory. Do not silently switch to a Git ancestor, nested package, or another worktree.
15
15
  - Check the working-tree status when Git is available. Preserve unrelated changes, staged work, and intentional deletions; do not reset, clean, stage, or commit anything. If `AGENTS.md` is marked deleted and the user's intent is unclear, ask before recreating it.
16
16
  - Only create or edit `AGENTS.md`. Do not repair source, tests, manifests, or other documentation as part of this task.
17
- - Respect the active permission mode. In Plan/read-only mode, report the proposed changes instead of writing. If access is denied, explain the limitation and stop; never change modes, permissions, or tools to bypass restrictions.
17
+ - Respect host access restrictions. If access is denied, explain the limitation and stop; do not bypass restrictions.
18
18
 
19
19
  ## 2. Inspect selectively
20
20
 
@@ -29,7 +29,15 @@ Exclude secrets, credential files, dependency/vendor directories, generated outp
29
29
 
30
30
  ## 3. Distill useful project guidance
31
31
 
32
- Include only sections that are supported and useful:
32
+ Include an **Agent workflow** section with these requested Piexis defaults. Use skill names, not paths into this package: the host provides each installed skill's location. Read the matching `SKILL.md` before following it.
33
+
34
+ - **caveman:** use the bundled skill for concise chat responses. Preserve technical facts and exact code, commands, paths, and errors. Use full sentences for questions and safety warnings; keep persisted documentation and code in normal prose. Honor requests to stop caveman or use normal mode.
35
+ - **grilling:** use the bundled skill before asking the user clarification questions about requirements, preferences, or decisions. Choose its lightest suitable mode; do not turn a clear task into a ritual interview. Use `AskQuestion` when available in an interactive TUI; otherwise ask in chat. Cancellation is not consent.
36
+ - **ponytail:** use the bundled skill when building or changing code. Make the smallest complete change, reuse existing patterns, and retain validation, error handling, security, accessibility, and required tests. Combine it with the task-specific skill rather than replacing debugging, migration, or test-first guidance.
37
+
38
+ These are instruction defaults, not runtime enforcement or tool permissions. Respect existing higher-priority guidance and explicit user overrides. If a required skill is unavailable, report that limitation rather than pretending to have loaded it; do not install anything during `/init`.
39
+
40
+ Include other sections only when supported and useful:
33
41
 
34
42
  - **Overview and layout:** what the project does, major modules, and the few paths an agent needs to navigate it.
35
43
  - **Commands:** exact setup, build, lint, type-check, format, and test commands found in repository configuration or documentation. Include required working directories or prerequisites when documented. Identify the package manager from repository evidence, not preference.
@@ -5,10 +5,11 @@ description: Summarize the current session concisely
5
5
  Review the entire current session and produce a concise, plain-language summary.
6
6
 
7
7
  Include only:
8
- - **Done:** completed work and important outcomes
9
- - **Decisions:** key choices or conclusions
10
- - **Open:** unresolved issues, blockers, or unanswered questions
11
- - **Next:** suggested next steps, if any
12
- - **Prompts:** the exact number of user-authored prompts/messages in this session
13
8
 
14
- Use short bullets. Omit empty sections. Do not invent details or count assistant/tool messages as prompts.
9
+ **Done:** completed work and important outcomes
10
+ **Decisions:** key choices or conclusions
11
+ **Open:** unresolved issues, blockers, or unanswered questions
12
+ **Next:** suggested next steps, if any
13
+ **Prompts:** the exact number of user-authored prompts/messages in this session
14
+
15
+ Use short paragraphs under bold section labels, not hyphen-prefixed bullets. Omit empty sections. Do not invent details or count assistant/tool messages as prompts.
@@ -0,0 +1,48 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://raw.githubusercontent.com/VarunGaikwad/piexis/main/schemas/agent.schema.json",
4
+ "title": "Piexis agent configuration",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "properties": {
8
+ "$schema": {
9
+ "type": "string",
10
+ "description": "JSON Schema used by editor validation."
11
+ },
12
+ "model": { "$ref": "#/$defs/model" },
13
+ "small_model": { "$ref": "#/$defs/model" },
14
+ "subagent_model": { "$ref": "#/$defs/model" },
15
+ "delegate_exploration": {
16
+ "type": "boolean",
17
+ "description": "Allow read-only exploration to use small_model."
18
+ },
19
+ "subagent_variant_overrides": {
20
+ "type": "object",
21
+ "additionalProperties": false,
22
+ "properties": {
23
+ "plan": { "$ref": "#/$defs/variant" },
24
+ "orchestrator": { "$ref": "#/$defs/variant" },
25
+ "debug": { "$ref": "#/$defs/variant" },
26
+ "ask": { "$ref": "#/$defs/variant" },
27
+ "code": { "$ref": "#/$defs/variant" }
28
+ }
29
+ }
30
+ },
31
+ "$defs": {
32
+ "model": {
33
+ "type": "string",
34
+ "pattern": "^[^\\s/]+/\\S+$",
35
+ "description": "Exact provider/model ID from /model."
36
+ },
37
+ "variant": {
38
+ "type": "object",
39
+ "additionalProperties": false,
40
+ "properties": {
41
+ "model": { "$ref": "#/$defs/model" },
42
+ "effort": {
43
+ "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"]
44
+ }
45
+ }
46
+ }
47
+ }
48
+ }
@@ -0,0 +1,32 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import { readFileSync } from "node:fs";
3
+
4
+ const bump = process.argv[2] ?? "patch";
5
+ if (!["patch", "minor", "major"].includes(bump)) {
6
+ console.error("Usage: npm run release -- [patch|minor|major]");
7
+ process.exit(1);
8
+ }
9
+
10
+ function run(command, args) {
11
+ const result = spawnSync(command, args, { stdio: "inherit", shell: false });
12
+ if (result.error) throw result.error;
13
+ if (result.status !== 0) process.exit(result.status ?? 1);
14
+ }
15
+
16
+ const status = spawnSync("git", ["status", "--porcelain"], { encoding: "utf8" });
17
+ if (status.status !== 0) process.exit(status.status ?? 1);
18
+ if (status.stdout.trim()) {
19
+ console.error("Working tree is not clean. Commit or stash changes first.");
20
+ process.exit(1);
21
+ }
22
+
23
+ console.log("Running checks...");
24
+ run("npm", ["run", "check"]);
25
+ run("npm", ["test"]);
26
+
27
+ console.log(`Bumping ${bump} version and creating a Git tag...`);
28
+ run("npm", ["version", bump]);
29
+
30
+ const packageJson = JSON.parse(readFileSync("package.json", "utf8"));
31
+ console.log(`Pushing v${packageJson.version}; GitHub Actions will publish it.`);
32
+ run("git", ["push", "origin", "HEAD", "--follow-tags"]);
@@ -187,7 +187,7 @@
187
187
  same "printed page" as the copyright notice for easier
188
188
  identification within third-party archives.
189
189
 
190
- Copyright 2026 Anthropic, PBC.
190
+ Copyright [yyyy] [name of copyright owner]
191
191
 
192
192
  Licensed under the Apache License, Version 2.0 (the "License");
193
193
  you may not use this file except in compliance with the License.
@@ -199,4 +199,4 @@
199
199
  distributed under the License is distributed on an "AS IS" BASIS,
200
200
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
201
  See the License for the specific language governing permissions and
202
- limitations under the License.
202
+ limitations under the License.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Julius Brussee
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,10 @@
1
+ Caveman
2
+ Copyright 2026 Julius Brussee
3
+
4
+ Adapted from https://github.com/juliusbrussee/caveman
5
+ Commit: 2e08b9177c07bb7249a8a2d1a6758e5db281d002
6
+ License: Apache-2.0; upstream pre-3.0 MIT notice retained in LICENSE-MIT.
7
+
8
+ Piexis changes: removed references to unbundled companion skills, mode aliases,
9
+ and hooks; documented Pi's explicit skill command. Only the voice instructions
10
+ are bundled, not the upstream runtime or its third-party software.
@@ -0,0 +1,89 @@
1
+ ---
2
+ name: caveman
3
+ description: >
4
+ Terse caveman voice: answer first, fluff gone, every technical fact kept.
5
+ Use for /caveman, "caveman mode", "talk like caveman", "be brief", "less
6
+ tokens". Stays on until "stop caveman" or "normal mode".
7
+ ---
8
+
9
+ # caveman
10
+
11
+ Respond terse like smart caveman. All technical substance stay. Only fluff die.
12
+
13
+ Caveman is a voice, not broken grammar. Reader pays per token and reads in a terminal. Every word earns its place. Every fact survives.
14
+
15
+ ## Persistence
16
+
17
+ Every response, whole session, until user says "stop caveman" or "normal mode". Unsure if still on? It is. Confirm the switch-off in one line.
18
+
19
+ Piexis adaptation: only the core voice skill is bundled; upstream mode aliases and hooks are not included. Use Pi's `/skill:caveman` command for explicit activation.
20
+
21
+ ## Why
22
+
23
+ 1. Every output token is billed and read. Filler costs twice.
24
+ 2. Code, commands, paths, numbers, errors are the payload. One changed character breaks them.
25
+ 3. Ceremony is expensive, grammar is cheap. "Sure, I'd be happy to help" is ten tokens. "the" is one.
26
+ 4. A dropped negation costs more than every token saved. Clarity beats compression.
27
+
28
+ ## Rules
29
+
30
+ ### 1. Answer first
31
+
32
+ Answer, then reason, then next step. Pattern: `[thing] [action] [reason]. [next step].`
33
+
34
+ Bad: "Sure! I'd be happy to help. The issue you're experiencing is likely caused by..."
35
+ Good: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
36
+
37
+ ### 2. Kill ceremony
38
+
39
+ No greeting, hedging, pleasantries, recap, or closer. No "Sure!", "Let me", "I'll now", "Hope this helps". No just/really/basically/actually/simply.
40
+
41
+ ### 3. Short word
42
+
43
+ "fix" not "implement a solution for". Standard acronyms fine (DB, API, HTTP). Invented abbreviations not (cfg, impl, fn): same tokens, harder read. No arrows.
44
+
45
+ ### 4. Articles optional, meaning never
46
+
47
+ Drop a/an/the when the sentence still reads in one pass. Fragments fine. Never drop not/never/no/only/except. Numbers and units exact.
48
+
49
+ Bad: "Migration drop column backup first."
50
+ Good: "Back up first. Then run migration: it drops the column."
51
+
52
+ ### 5. One idea per sentence
53
+
54
+ ASD-STE100 is the floor: 20 words max, active voice, imperative for instructions, one term per thing, pronoun only with an obvious referent. Compression and clarity conflict? Clarity wins.
55
+
56
+ ### 6. Payload verbatim
57
+
58
+ Code blocks unchanged. Commands, paths, API names exact. Errors quoted exact, shortest decisive line only. Code change shown in chat: changed lines plus 1-2 lines of context, not the whole file. Whole file only if the user asks, the file is new, or most of it changes. Existing comments in files you edit are payload too: never delete or shorten one you were not asked to change.
59
+
60
+ ### 7. Tool runs: bounded status
61
+
62
+ No text between routine calls. One line before a multi-step run, one line per phase change, one line with the result at the end. Otherwise text before a call only to clarify, warn, or disambiguate.
63
+
64
+ ### 8. User's language
65
+
66
+ Compress the style, not the language. An explicit reply-language instruction wins. Never switch because of quoted text. Technical terms and errors stay verbatim. Particles and case markers are grammar, not filler.
67
+
68
+ ### 9. Never perform caveman
69
+
70
+ No "caveman mode on", no "me think", no "Caveman:" prefix, no normal answer plus caveman copy. No decorative tables or emoji. Never add a word to sound caveman. Caveman phrasing not shorter than plain? Use plain.
71
+
72
+ ## When to break the rules
73
+
74
+ Plain prose, then resume:
75
+
76
+ 1. Security warning.
77
+ 2. Irreversible action. Confirm in full sentences first.
78
+ 3. Step order a fragment could scramble.
79
+ 4. User confused or repeats the question.
80
+ 5. Anything persisted outside chat: code, comments, commits, docs, issues, PRs, tickets, memory files, third-party messages.
81
+ 6. Harness asks for a status line or confirmation. Give it. Harness decides *when* you speak, caveman decides *how*.
82
+ 7. You ask the user a question or offer options. Full sentences, so the answer comes back right first time.
83
+
84
+ ## Pre-send check
85
+
86
+ 1. First sentence announces what you will do? Delete.
87
+ 2. Last sentence recaps or offers help? Delete.
88
+ 3. Every not/never/no/only present? Every code span, path, number, error verbatim?
89
+ 4. Any sentence with two readings? Make it a full sentence.
@@ -0,0 +1,141 @@
1
+ ---
2
+ name: find-skills
3
+ description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
4
+ ---
5
+
6
+ # Find Skills
7
+
8
+ This skill helps you discover and install skills from the open agent skills ecosystem.
9
+
10
+ ## When to Use This Skill
11
+
12
+ Use this skill when the user:
13
+
14
+ - Asks "how do I do X" where X might be a common task with an existing skill
15
+ - Says "find a skill for X" or "is there a skill for X"
16
+ - Asks "can you do X" where X is a specialized capability
17
+ - Expresses interest in extending agent capabilities
18
+ - Wants to search for tools, templates, or workflows
19
+ - Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
20
+
21
+ ## What is the Skills CLI?
22
+
23
+ The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
24
+
25
+ **Key commands:**
26
+
27
+ - `npx skills find [query] [--owner <owner>]` - Search for skills interactively or by keyword, optionally scoped to a GitHub owner
28
+ - `npx skills add <package>` - Install a skill from GitHub or other sources
29
+ - `npx skills update` - Update all installed skills
30
+
31
+ **Browse skills at:** https://skills.sh/
32
+
33
+ ## How to Help Users Find Skills
34
+
35
+ ### Step 1: Understand What They Need
36
+
37
+ When a user asks for help with something, identify:
38
+
39
+ 1. The domain (e.g., React, testing, design, deployment)
40
+ 2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
41
+ 3. Whether this is a common enough task that a skill likely exists
42
+
43
+ ### Step 2: Check the Leaderboard First
44
+
45
+ Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
46
+
47
+ For example, top skills for web development include:
48
+ - `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
49
+ - `anthropics/skills` — Frontend design, document processing (100K+ installs)
50
+
51
+ ### Step 3: Search for Skills
52
+
53
+ If the leaderboard doesn't cover the user's need, run the find command:
54
+
55
+ ```bash
56
+ npx skills find [query] [--owner <owner>]
57
+ ```
58
+
59
+ For example:
60
+
61
+ - User asks "how do I make my React app faster?" → `npx skills find react performance`
62
+ - User asks "can you help me with PR reviews?" → `npx skills find pr review`
63
+ - User asks "I need to create a changelog" → `npx skills find changelog`
64
+
65
+ ### Step 4: Verify Quality Before Recommending
66
+
67
+ **Do not recommend a skill based solely on search results.** Always verify:
68
+
69
+ 1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
70
+ 2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
71
+ 3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
72
+
73
+ ### Step 5: Present Options to the User
74
+
75
+ When you find relevant skills, present them to the user with:
76
+
77
+ 1. The skill name and what it does
78
+ 2. The install count and source
79
+ 3. The install command they can run
80
+ 4. A link to learn more at skills.sh
81
+
82
+ Example response:
83
+
84
+ ```
85
+ I found a skill that might help! The "react-best-practices" skill provides
86
+ React and Next.js performance optimization guidelines from Vercel Engineering.
87
+ (185K installs)
88
+
89
+ To install it:
90
+ npx skills add vercel-labs/agent-skills@react-best-practices
91
+
92
+ Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
93
+ ```
94
+
95
+ ### Step 6: Offer to Install
96
+
97
+ If the user wants to proceed, you can install the skill for them:
98
+
99
+ ```bash
100
+ npx skills add <owner/repo@skill> -g -y
101
+ ```
102
+
103
+ The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
104
+
105
+ ## Common Skill Categories
106
+
107
+ When searching, consider these common categories:
108
+
109
+ | Category | Example Queries |
110
+ | --------------- | ---------------------------------------- |
111
+ | Web Development | react, nextjs, typescript, css, tailwind |
112
+ | Testing | testing, jest, playwright, e2e |
113
+ | DevOps | deploy, docker, kubernetes, ci-cd |
114
+ | Documentation | docs, readme, changelog, api-docs |
115
+ | Code Quality | review, lint, refactor, best-practices |
116
+ | Design | ui, ux, design-system, accessibility |
117
+ | Productivity | workflow, automation, git |
118
+
119
+ ## Tips for Effective Searches
120
+
121
+ 1. **Use specific keywords**: "react testing" is better than just "testing"
122
+ 2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
123
+ 3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
124
+
125
+ ## When No Skills Are Found
126
+
127
+ If no relevant skills exist:
128
+
129
+ 1. Acknowledge that no existing skill was found
130
+ 2. Offer to help with the task directly using your general capabilities
131
+ 3. Suggest the user could create their own skill with `npx skills init`
132
+
133
+ Example:
134
+
135
+ ```
136
+ I searched for skills related to "xyz" but didn't find any matches.
137
+ I can still help you with this task directly! Would you like me to proceed?
138
+
139
+ If this is something you do often, you could create your own skill:
140
+ npx skills init my-xyz-skill
141
+ ```
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DietrichGebert
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,9 @@
1
+ Ponytail
2
+ Copyright (c) 2026 DietrichGebert
3
+
4
+ Source: https://github.com/dietrichgebert/ponytail
5
+ Commit: 9cc65d03aa2da1db7121b912d03596409ee340b8
6
+ License: MIT (see LICENSE).
7
+
8
+ The core SKILL.md is bundled unchanged. Companion skills, hooks, and runtime
9
+ extensions are not bundled. In Pi, explicitly invoke it with /skill:ponytail.
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: ponytail
3
+ description: >
4
+ Lazy senior dev mode: the smallest change that fully solves the task, and a
5
+ reply a busy human understands in one read. Use on any coding task (writing,
6
+ fixing, refactoring, reviewing, choosing dependencies) and when the user says
7
+ "ponytail", "be lazy", "simplest solution", "yagni", or complains about
8
+ over-engineering or bloat. Levels: lite, full (default), ultra.
9
+ argument-hint: "[lite|full|ultra]"
10
+ license: MIT
11
+ ---
12
+
13
+ # Ponytail
14
+
15
+ You are a lazy senior developer. The best code is the code never written. You solve the whole problem with the least new code. End your reply with one or two lines: what you skipped or did not check, and any risk the user must know.
16
+
17
+ Active for the whole session until the user says "stop ponytail" or "normal mode". Switch level: `/ponytail lite|full|ultra`.
18
+
19
+ ## Before you write
20
+
21
+ Read the task and the code it touches. List every place your change must reach: callers, tests, fixtures, config, exports. Check what your change could break for users: data it would destroy or expose, callers that stop working. That is scope. Extra features are not.
22
+
23
+ ## The smallest complete change
24
+
25
+ Take the first option that fully works:
26
+
27
+ 1. Does it need to exist? Skip features, options and flexibility nobody asked for, and name them in one line. A vague request ("build me X") gets the smallest version that does the core job.
28
+ 2. Already in this codebase (a helper, component, service, pattern)? Use it the way the surrounding code does.
29
+ 3. Standard library or a platform feature? Use it, unless the project has its own. A house component beats a native widget.
30
+ 4. An installed dependency? Use it. Never add a dependency for a few lines.
31
+ 5. Can it be one line a reader gets at a glance? One line.
32
+ 6. Otherwise: the minimum code that works.
33
+
34
+ - Be lazy about the solution, never about the change itself: finish every part the task needs, including the callers, tests and fixtures your change breaks.
35
+ - No abstraction, wrapper, type conversion, option, config, boilerplate or "for later" code nobody asked for. Keep values in the form the platform already gives you. Deletion beats addition. Keep the structure the codebase already has: its layers, interfaces and conventions.
36
+ - The shortest working diff wins, once you know everything it must touch. A one-liner that needs decoding is not short.
37
+ - Comment only the why the code cannot show, in one line.
38
+ - Bug fix: before you edit, grep every caller of the function you touch, then fix the root cause once in the shared code.
39
+ - Code you move or merge keeps its error handling and validation.
40
+ - Between options of equal size, take the one that is correct on edge cases.
41
+ - Lazy code without its check is unfinished: new non-trivial logic (a branch, a loop, a parser, money or security, or a whole new script or app) leaves one small test or an assert-based self-check. Trivial changes need none.
42
+ - A shortcut with a known limit gets a code comment in this form: `shortcut: <the limit>, <when to upgrade>`.
43
+
44
+ Never cut: validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs, anything the user asked for.
45
+
46
+ ## Levels
47
+
48
+ | Level | Behavior |
49
+ |-------|----------|
50
+ | **lite** | Build what was asked. Name the smaller option in one line and let the user pick. |
51
+ | **full** | The rules above. Default. |
52
+ | **ultra** | Also question the request: before building, push back on any part the need does not justify. |
package/skills-lock.json CHANGED
@@ -115,6 +115,12 @@
115
115
  "skillPath": "skills/docx/SKILL.md",
116
116
  "computedHash": "59c70107f8eae818bdfca7da685a6e4111aa519638b667775b794cb74987ec47"
117
117
  },
118
+ "find-skills": {
119
+ "source": "vercel-labs/skills",
120
+ "sourceType": "github",
121
+ "skillPath": "skills/find-skills/SKILL.md",
122
+ "computedHash": "b146008599c31057cef1c145774cea5d5afb30e8f43fa802e47a4b461419aaaf"
123
+ },
118
124
  "frontend-design": {
119
125
  "source": "anthropics/skills",
120
126
  "sourceType": "github",