[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CEX02P2FT3ZJNBASMWGS55":3,"skill-same:01M7CEX02P2FT3ZJNBASMWGS55":55},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":28,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M7CEX02P2FT3ZJNBASMWGS55","tool-prompt-optimization",null,"lukaszraczylo\u002Foh-my-pi-schema","lukaszraczylo","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F2182556?v=4","01M74GZHGZKZZ6SC3SWY432EAB","Lukasz Raczylo","01M7CET8G0EGD8XPJKDR0C46WN",0,"MIT","https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema\u002Fblob\u002Fmain\u002F.omp\u002Fskills\u002Ftool-prompt-optimization\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: tool-prompt-optimization\ndescription: Optimize the description prompts an AI agent reads to learn its built-in tools (the `.md` files under prompts\u002Ftools\u002F). Two halves: (1) measure how much of a prompt is already inferable from the tool's JSON parameter schema + name, to prune redundancy with evidence; (2) house authoring rules for what belongs in a tool prompt vs what stays in code. Use when auditing, trimming, writing, or reviewing tool prompts, deciding what schema field descriptions already cover, or testing schema-vs-prompt overlap before deleting prompt lines.\n---\n\n# Tool Prompt Optimization\n\nPrompt\u002Fschema overlap: content reconstructible from `(name, JSON schema, blank outline)` is a *prune candidate*, never an automatic delete. Probe this overlap for evidence, not vibes: predict the prompt body from those inputs. Reliably recovered lines: candidates; no-model recovery: load-bearing — keep.\n\n## Run probe\n\n`scripts\u002Fprobe.ts`: `@oh-my-pi\u002Fpi-ai` `completeSimple`; production-matching model\u002Fauth\u002Fprovider behavior.\n\n```bash\nbun .omp\u002Fskills\u002Ftool-prompt-optimization\u002Fscripts\u002Fprobe.ts \\\n  --schema \u003Cfile|json> --template \u003Cfile|text> --name \u003Ctool_name>\n```\n\n- Required: `--schema`, `--template` — file path or inline value.\n- No `--model`: panel `fireworks\u002Fkimi-k2.7-code`, `anthropic\u002Fclaude-opus-4-8`, `openai\u002Fgpt-5.5` × `--samples` (default 3); requires `FIREWORKS_API_KEY` \u002F `ANTHROPIC_API_KEY` \u002F `OPENAI_API_KEY`.\n- `--model p\u002Fid,p\u002Fid`: override panel. Tune: `--samples N`, `--max-tokens`, `--json`.\n- Programmatic: `import { probe } from \".\u002Fscripts\u002Fprobe.ts\"` → `{ prompt, results: [{ model, samples: [{ text, stopReason, usage, error }] }] }`.\n\n### Builtin shortcut — preferred for this repo\n\n`scripts\u002Fprobe-builtin.ts` instantiates the live tool; gets exact `toolWireSchema`, `tool.description`, and derived outline:\n\n```bash\nbun .omp\u002Fskills\u002Ftool-prompt-optimization\u002Fscripts\u002Fprobe-builtin.ts --tool \u003Cname> [--no-summary] [--show]\n```\n\n- `--show`: resolved schema, derived outline, real prompt; exits without API calls. Inspect before spending tokens.\n- `--no-summary`: direct summary-line-blank ablation.\n- `--samples` \u002F `--model` \u002F `--max-tokens` \u002F `--json`: panel passthrough. Output ends with real prompt for in-place diff.\n- Factory-map bypasses settings allowlist: gated `irc`, `github`, … resolve. Construction availability gate (e.g. missing `gh` CLI) → manual inputs.\n\n## Inputs\n\n**Schema:** wire schema the model sees, never hand-sketch. Arktype:\n\n```ts\nimport { arkToWireSchema } from \"@oh-my-pi\u002Fpi-ai\"; \u002F\u002F or toolWireSchema(tool)\nJSON.stringify(arkToWireSchema(toolSchema), null, 2);\n```\n\nInclude `required`, `additionalProperties: false`; omission makes usage appear looser than reality.\n\n**Template:** actual `.md` structure with bodies blanked — one-line summary, then each section tag containing `...`.\n\n```\nStructural code search via native ast-grep AST matching.\n\n\u003Cinstruction>\n...\n\u003C\u002Finstruction>\n\n\u003Coutput>\n...\n\u003C\u002Foutput>\n\n\u003Ccritical>\n...\n\u003C\u002Fcritical>\n```\n\n## Interpret\n\nBucket each real-prompt line:\n\n- **Prune candidate:** stable across samples **and** models; schema restatement — parameter names\u002Ftypes, `required`, field-description value examples, stated clamp ranges.\n- **Keep:** no model recovers it — defaults\u002Fdirection (`gitignore` default true); routing\u002Fescalation (`NEVER` shell out to `find`\u002F`fd` → use this tool; broad exploration → `Task` subagent); exact output shape (mtime sort, grouping, `artifact:\u002F\u002F` truncation); worked anti-patterns; type-invisible constraints (AST metavariable grammar, C++ trailing `;`).\n\nOne sample: noise. Stable cross-sample\u002Fmodel overlap is only a candidate; history must clear it. MUST NOT delete on inferability alone.\n\n## Caveats — before every deletion\n\n- **MUST `git blame` each cut line; read its commit\u002Fissue.** Many lines are incident scar tissue: hallucinated flag, shell-out, repo-root scan, fabricated anchor. Keep scar tissue. History distinguishes schema restatement from incident prevention. Inferability necessary, NEVER sufficient.\n- **Memorization ≠ inference:** public repos, including this one, may be training data. Repo-specific prediction absent from schema — exact tool names, internal URI schemes, `Task` subagent — is recitation; discount it.\n- **Outline leaks:** summary and section names hint. For schema-alone inference, second pass: no summary, generic section tags. Content surviving only the summary is summary-inferable, not schema-inferable.\n\n## Verdict\n\nPredictions usually recover schema-covered parameter mechanics\u002Fgeneric usage, not defaults, output shape, routing, anti-patterns, domain grammar. Prune the former only after per-line `git blame`; keep the latter. Self-documenting flag tools (`find`) prune heavily; DSL\u002Fcapability tools (`read`, `ast_grep`) barely.\n\n## Tool Prompt Authoring\n\nTool prompts are not API docs: teach when to choose a tool, input shape, and agent-owned failures. Engine internals, recovery heuristics, fallback chains, performance tuning: code.\n\n### Surface, not machinery\n\nAgents choose from prose, not source: tell WHEN\u002FWHY, NEVER internal HOW.\n\n- `read.md`: every covered source — file\u002Fdir\u002Farchive\u002Fsqlite\u002FPDF\u002FURL — prevents `cat`\u002F`curl`\u002F`tar`; omit chunker, binary sniffer, cache layer.\n- `lsp.md`: \"You MUST use `lsp` whenever a language server is available — safer than text-based alternatives.\" Omit LSP wire protocol, server lifecycle, capability negotiation.\n- `ast_edit`: metavariable syntax\u002Fworkflow: \"Loosest existence check: `pat: 'executeBash'` with narrow paths\"; omit AST engine, query compilation, tree-sitter grammar selection.\n- `hashline.md` (this repo): patch grammar — anchors, ops, payloads, ranges — and successful edit shapes. Hide `tryRecoverHashlineWithCache`, fuzz factor, bigram tables, `findUniqueSuffixMatch`, `untilAborted`, `formatGroupedFiles`; agent sees only \"the tool resolved your typo\" or \"the anchor was stale, re-read\".\n\nIf a detail cannot change agent behavior, it does NOT belong. Each sentence MUST shift an agent decision.\n\n### Good prompt anatomy\n\n1. **One-line purpose:** agent-vocabulary problem; not \"wraps libfoo with X\", but \"compact, line-anchored edit format\".\n2. **Input grammar\u002Fsurface:** operators, parameters, selectors; concrete emitted syntax.\n3. **Worked examples:** 3–8 common shapes. Example IS explanation; do not narrate twice.\n4. **Agent-owned failure shapes:** input-fixable stale anchors, missing payload prefix, fabricated hash; omit silently recovered failures.\n5. **Anti-patterns:** real-failure WRONG\u002FRIGHT pairs for retry-causing mistakes, never imagined ones.\n6. **`\u003Ccritical>` recap:** 3–6 load-bearing lines for agents skipping body.\n\n### Exclude\n\n- Implementation file\u002Ffunction names, module layout.\n- Recovery, retry, normalization, caching, fuzz matching.\n- Performance characteristics such as \"this is O(n)\", unless strategy-changing.\n- Telemetry, logging, debug flags, unsettable env vars.\n- Version history, deprecated parameters, \"previously this worked differently\".\n- Cross-tool plumbing such as \"this calls `read` under the hood\", unless coordination required.\n","# Tool Prompt Optimization\n\nPrompt\u002Fschema overlap: content reconstructible from `(name, JSON schema, blank outline)` is a *prune candidate*, never an automatic delete. Probe this overlap for evidence, not vibes: predict the prompt body from those inputs. Reliably recovered lines: candidates; no-model recovery: load-bearing — keep.\n\n## Run probe\n\n`scripts\u002Fprobe.ts`: `@oh-my-pi\u002Fpi-ai` `completeSimple`; production-matching model\u002Fauth\u002Fprovider behavior.\n\n```bash\nbun .omp\u002Fskills\u002Ftool-prompt-optimization\u002Fscripts\u002Fprobe.ts \\\n  --schema \u003Cfile|json> --template \u003Cfile|text> --name \u003Ctool_name>\n```\n\n- Required: `--schema`, `--template` — file path or inline value.\n- No `--model`: panel `fireworks\u002Fkimi-k2.7-code`, `anthropic\u002Fclaude-opus-4-8`, `openai\u002Fgpt-5.5` × `--samples` (default 3); requires `FIREWORKS_API_KEY` \u002F `ANTHROPIC_API_KEY` \u002F `OPENAI_API_KEY`.\n- `--model p\u002Fid,p\u002Fid`: override panel. Tune: `--samples N`, `--max-tokens`, `--json`.\n- Programmatic: `import { probe } from \".\u002Fscripts\u002Fprobe.ts\"` → `{ prompt, results: [{ model, samples: [{ text, stopReason, usage, error }] }] }`.\n\n### Builtin shortcut — preferred for this repo\n\n`scripts\u002Fprobe-builtin.ts` instantiates the live tool; gets exact `toolWireSchema`, `tool.description`, and derived outline:\n\n```bash\nbun .omp\u002Fskills\u002Ftool-prompt-optimization\u002Fscripts\u002Fprobe-builtin.ts --tool \u003Cname> [--no-summary] [--show]\n```\n\n- `--show`: resolved schema, derived outline, real prompt; exits without API calls. Inspect before spending tokens.\n- `--no-summary`: direct summary-line-blank ablation.\n- `--samples` \u002F `--model` \u002F `--max-tokens` \u002F `--json`: panel passthrough. Output ends with real prompt for in-place diff.\n- Factory-map bypasses settings allowlist: gated `irc`, `github`, … resolve. Construction availability gate (e.g. missing `gh` CLI) → manual inputs.\n\n## Inputs\n\n**Schema:** wire schema the model sees, never hand-sketch. Arktype:\n\n```ts\nimport { arkToWireSchema } from \"@oh-my-pi\u002Fpi-ai\"; \u002F\u002F or toolWireSchema(tool)\nJSON.stringify(arkToWireSchema(toolSchema), null, 2);\n```\n\nInclude `required`, `additionalProperties: false`; omission makes usage appear looser than reality.\n\n**Template:** actual `.md` structure with bodies blanked — one-line summary, then each section tag containing `...`.\n\n```\nStructural code search via native ast-grep AST matching.\n\n\u003Cinstruction>\n...\n\u003C\u002Finstruction>\n\n\u003Coutput>\n...\n\u003C\u002Foutput>\n\n\u003Ccritical>\n...\n\u003C\u002Fcritical>\n```\n\n## Interpret\n\nBucket each real-prompt line:\n\n- **Prune candidate:** stable across samples **and** models; schema restatement — parameter names\u002Ftypes, `required`, field-description value examples, stated clamp ranges.\n- **Keep:** no model recovers it — defaults\u002Fdirection (`gitignore` default true); routing\u002Fescalation (`NEVER` shell out to `find`\u002F`fd` → use this tool; broad exploration → `Task` subagent); exact output shape (mtime sort, grouping, `artifact:\u002F\u002F` truncation); worked anti-patterns; type-invisible constraints (AST metavariable grammar, C++ trailing `;`).\n\nOne sample: noise. Stable cross-sample\u002Fmodel overlap is only a candidate; history must clear it. MUST NOT delete on inferability alone.\n\n## Caveats — before every deletion\n\n- **MUST `git blame` each cut line; read its commit\u002Fissue.** Many lines are incident scar tissue: hallucinated flag, shell-out, repo-root scan, fabricated anchor. Keep scar tissue. History distinguishes schema restatement from incident prevention. Inferability necessary, NEVER sufficient.\n- **Memorization ≠ inference:** public repos, including this one, may be training data. Repo-specific prediction absent from schema — exact tool names, internal URI schemes, `Task` subagent — is recitation; discount it.\n- **Outline leaks:** summary and section names hint. For schema-alone inference, second pass: no summary, generic section tags. Content surviving only the summary is summary-inferable, not schema-inferable.\n\n## Verdict\n\nPredictions usually recover schema-covered parameter mechanics\u002Fgeneric usage, not defaults, output shape, routing, anti-patterns, domain grammar. Prune the former only after per-line `git blame`; keep the latter. Self-documenting flag tools (`find`) prune heavily; DSL\u002Fcapability tools (`read`, `ast_grep`) barely.\n\n## Tool Prompt Authoring\n\nTool prompts are not API docs: teach when to choose a tool, input shape, and agent-owned failures. Engine internals, recovery heuristics, fallback chains, performance tuning: code.\n\n### Surface, not machinery\n\nAgents choose from prose, not source: tell WHEN\u002FWHY, NEVER internal HOW.\n\n- `read.md`: every covered source — file\u002Fdir\u002Farchive\u002Fsqlite\u002FPDF\u002FURL — prevents `cat`\u002F`curl`\u002F`tar`; omit chunker, binary sniffer, cache layer.\n- `lsp.md`: \"You MUST use `lsp` whenever a language server is available — safer than text-based alternatives.\" Omit LSP wire protocol, server lifecycle, capability negotiation.\n- `ast_edit`: metavariable syntax\u002Fworkflow: \"Loosest existence check: `pat: 'executeBash'` with narrow paths\"; omit AST engine, query compilation, tree-sitter grammar selection.\n- `hashline.md` (this repo): patch grammar — anchors, ops, payloads, ranges — and successful edit shapes. Hide `tryRecoverHashlineWithCache`, fuzz factor, bigram tables, `findUniqueSuffixMatch`, `untilAborted`, `formatGroupedFiles`; agent sees only \"the tool resolved your typo\" or \"the anchor was stale, re-read\".\n\nIf a detail cannot change agent behavior, it does NOT belong. Each sentence MUST shift an agent decision.\n\n### Good prompt anatomy\n\n1. **One-line purpose:** agent-vocabulary problem; not \"wraps libfoo with X\", but \"compact, line-anchored edit format\".\n2. **Input grammar\u002Fsurface:** operators, parameters, selectors; concrete emitted syntax.\n3. **Worked examples:** 3–8 common shapes. Example IS explanation; do not narrate twice.\n4. **Agent-owned failure shapes:** input-fixable stale anchors, missing payload prefix, fabricated hash; omit silently recovered failures.\n5. **Anti-patterns:** real-failure WRONG\u002FRIGHT pairs for retry-causing mistakes, never imagined ones.\n6. **`\u003Ccritical>` recap:** 3–6 load-bearing lines for agents skipping body.\n\n### Exclude\n\n- Implementation file\u002Ffunction names, module layout.\n- Recovery, retry, normalization, caching, fuzz matching.\n- Performance characteristics such as \"this is O(n)\", unless strategy-changing.\n- Telemetry, logging, debug flags, unsettable env vars.\n- Version history, deprecated parameters, \"previously this worked differently\".\n- Cross-tool plumbing such as \"this calls `read` under the hood\", unless coordination required.\n",{},"main","b67632f9a010ad314c25c9473185c3b21c5cdeee",".omp\u002Fskills\u002Ftool-prompt-optimization","https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema","https:\u002F\u002Fgithub.com\u002Flukaszraczylo","raczylo.com","Working with tech since the age of 6 but I won't push the code written in BASIC.","2026-10-18 23:09:50",{"source":7,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add lukaszraczylo\u002Foh-my-pi-schema --skill tool-prompt-optimization",{"tool":37,"command":38},"bunx","bunx skills add lukaszraczylo\u002Foh-my-pi-schema --skill tool-prompt-optimization",{"tool":40,"command":41},"pnpm","pnpm dlx skills add lukaszraczylo\u002Foh-my-pi-schema --skill tool-prompt-optimization","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema\u002Fblob\u002Fmain\u002F.omp\u002Fskills\u002Ftool-prompt-optimization\u002FSKILL.md",true,[45,51],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"scripts\u002Fprobe-builtin.ts","SCRIPT","脚本",6075,"https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema\u002Fblob\u002Fmain\u002F.omp\u002Fskills\u002Ftool-prompt-optimization\u002Fscripts\u002Fprobe-builtin.ts",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"scripts\u002Fprobe.ts",7990,"https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema\u002Fblob\u002Fmain\u002F.omp\u002Fskills\u002Ftool-prompt-optimization\u002Fscripts\u002Fprobe.ts",[56,63,70,77,83,90],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":18},"01M7CEXR6DWJ94NMXNK1XMD7VS","greet","A greeting skill for testing","https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema\u002Fblob\u002Fmain\u002Fpackages\u002Fcoding-agent\u002Ftest\u002Fmarketplace\u002Ffixtures\u002Fvalid-marketplace\u002Fplugins\u002Fhello-plugin\u002Fskills\u002Fgreet\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":18},"01M7CEXQ2VBP8XG35Z5MN454XG","valid-skill","A valid skill for testing purposes.","https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema\u002Fblob\u002Fmain\u002Fpackages\u002Fcoding-agent\u002Ftest\u002Ffixtures\u002Fskills\u002Fvalid-skill\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":18},"01M7CEXP050618ZXMATPF1V7WQ","unknown-field","A skill with an unknown frontmatter field.","https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema\u002Fblob\u002Fmain\u002Fpackages\u002Fcoding-agent\u002Ftest\u002Ffixtures\u002Fskills\u002Funknown-field\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":18},"01M7CEXMV0FRMZ83DDDNE4CEEB","no-frontmatter","https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema\u002Fblob\u002Fmain\u002Fpackages\u002Fcoding-agent\u002Ftest\u002Ffixtures\u002Fskills\u002Fno-frontmatter\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":18},"01M7CEXKTSTMZG03NAPTAPF32W","child-skill","A nested skill in a subdirectory.","https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema\u002Fblob\u002Fmain\u002Fpackages\u002Fcoding-agent\u002Ftest\u002Ffixtures\u002Fskills\u002Fnested\u002Fchild-skill\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":18},"01M7CEXJR0VX6S9WZYVSMDXSXS","different-name","A skill with a name that doesn't match the directory.","https:\u002F\u002Fgithub.com\u002Flukaszraczylo\u002Foh-my-pi-schema\u002Fblob\u002Fmain\u002Fpackages\u002Fcoding-agent\u002Ftest\u002Ffixtures\u002Fskills\u002Fname-mismatch\u002FSKILL.md",[],[]]