[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79RFEMWDYHTQW6DJV3NC0S7":3,"skill-same:01M79RFEMWDYHTQW6DJV3NC0S7":44},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M79RFEMWDYHTQW6DJV3NC0S7","turtle",null,"Read and propose Turtle project-bucket context - local resources, external services, handoffs, and restore plans - through the `turtle` CLI. Use when asked what a project contains, where its external services live, what the handoff says, or to record a folder, URL, external resource, or handoff into a project bucket. Also use before starting work on a project that has a Turtle bucket, to recover context instead of reconstructing it.","op-q\u002Fturtle","op-q","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F141008398?v=4","01M79RFAXTRC6YF06ZYH7A5FSE","Software Engineer","01M79RFAYD6BFNC0N2XFHTGPPD",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fop-q\u002Fturtle\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fturtle\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: turtle\ndescription: Read and propose Turtle project-bucket context - local resources, external services, handoffs, and restore plans - through the `turtle` CLI. Use when asked what a project contains, where its external services live, what the handoff says, or to record a folder, URL, external resource, or handoff into a project bucket. Also use before starting work on a project that has a Turtle bucket, to recover context instead of reconstructing it.\n---\n\n# Turtle project buckets\n\nTurtle keeps everything needed to understand and resume a project — local resources, external\nservice references, working state, and safe context — in one private local bucket.\n\nYou can **read** any bucket and **propose** additions. You can never write one.\n\n## Before anything else: is the runtime up?\n\nThe CLI is a thin client over a Unix socket. Nothing works without the runtime.\n\n```bash\nturtle project list\n```\n\n- `runtime_unavailable` → nothing is running. Ask the user to start either `turtle app` (desktop\n  companion plus the runtime) or `turtle serve` (headless). **Do not start it yourself** — it is\n  the sole writer, and a second one would fight the first for the socket.\n- In this repository, use `.\u002Fscripts\u002Fturtle` instead of `turtle`.\n\n`turtle app` and `turtle serve` are mutually exclusive; `turtle app` already serves the socket, so\nevery command below works the same either way.\n\n`XDG_RUNTIME_DIR` must be set. Turtle deliberately has no `\u002Ftmp` fallback.\n\n## The one rule that matters\n\n**Proposals are yours. Decisions are the user's.**\n\nEvery write goes through a `CaptureProposal` that a human must approve. `turtle capture accept`\nrequires an interactive terminal *and* the user typing the exact proposal ID. Piped or scripted\nstdin is refused with `confirmation_required` and exit code 2.\n\nThis is not a limitation to work around. Never attempt to accept a proposal on the user's behalf,\nnever write bucket files directly, and never edit anything under the Turtle data root. Propose,\nthen show the user the proposal ID and let them accept.\n\n## Reading context\n\nStart here when you need to understand a project:\n\n```bash\nturtle context show                          # full bucket as Markdown\nturtle context show --format json            # same content, structured\nturtle context show --project \u003Cid-or-name>   # a project other than the selected one\n```\n\n`context show` returns everything at once: handoff, local resources, external resources, agents.\nPrefer it over assembling the narrower commands.\n\nNarrower reads:\n\n```bash\nturtle handoff show                # Current state \u002F Next \u002F Important\nturtle external list               # id, provider, kind, label, url\nturtle agents list                 # id, kind, label, cwd, resume hint\nturtle restore plan                # side-effect-free; prints actions, opens nothing\nturtle project list                # `*` marks the selected project\nturtle capture show \u003Cproposal-id>  # exactly what a pending proposal would store\nturtle status                      # is the runtime up, and what is installed\n```\n\n`restore plan` never opens or launches anything. It is safe to run.\n\n`turtle status` is the exception to the rule above: it is the one command that works with no\nruntime listening, so it is what to run when everything else answers `runtime_unavailable`.\n\n## Three things only the user may do\n\nThese change the user's machine directly and none of them goes through the proposal queue. Print\nthe command and let the user run it.\n\n```bash\nturtle here                         # this folder becomes a selected, scanned project\nturtle project add-root \u002Fabs\u002Fpath   # widens what Turtle is allowed to scan\nturtle restore run                  # actually opens folders, files, and URLs\n```\n\n`turtle here` is the fastest setup path — it selects or creates the project for a folder, approves\nthat folder, and scans it in one step — but it both creates a project and widens the scan scope, so\nit is the user's call. Suggest it when a project has no bucket yet.\n\n`project add-root` is the only way to approve a further folder for an existing project, and\napproving a root is what lets the collectors read it. Widening that scope is the user's call, not\nyours.\n\n`restore run` opens real windows on the user's desktop. Run it only when the user has asked for a\nrestore in that turn. It reports `opened` and `failed` per resource, never stops at the first\nfailure, and never closes anything. `--only \u003Cresource-id>` restores a single resource; get IDs\nfrom `turtle restore plan`.\n\n## Letting Turtle find things for itself\n\n```bash\nturtle inspect                      # scan approved roots, queue what is new\nturtle inspect --format json        # queued \u002F skipped \u002F failures\n```\n\nThe bundled collectors read the approved roots and propose a git remote as an external resource,\nthe repository root, README and manifests as local resources, and `.env.example` variable *names*\nonly. Everything they find is marked `detected`, never `confirmed`, and lands in the same review\nqueue as a manual proposal — **detection never stores anything**.\n\nOne more collector reads outside the roots, by design: it looks at the local Codex CLI's own\nsession headers and proposes an agent reference for any session whose working directory is inside\nan approved root. It reads the first line of a rollout file and nothing else, so no conversation\ncontent is ever read, and it degrades to a reported failure if Codex changes that format.\n\nFindings that already match a stored record come back under `skipped` with reason\n`already_stored`, one the user dismissed comes back as `dismissed` and is never re-offered, and a\nfinding still awaiting a decision is simply listed again — so running it repeatedly is safe and\nidempotent. The desktop window scans a project by itself whenever it is opened, so a finding you\nsee there may already be waiting without anyone having run `inspect`. Prefer `turtle inspect` over\nhand-writing proposals for anything a collector can find; it produces better provenance\n(`collector:git@1`) and real evidence.\n\n## Proposing\n\nAll proposal commands print a proposal ID and exit without changing the bucket.\n\n```bash\nturtle capture folder        --label \"Repo\"  --path \u002Fabs\u002Fpath\u002Finside\u002Fan\u002Fapproved\u002Froot\nturtle capture documentation --label \"Plan\"  --url https:\u002F\u002Fexample.com\u002Fplan\nturtle capture url           --label \"Board\" --url https:\u002F\u002Fexample.com\u002Fboard\n\nturtle handoff propose --current-state \"...\" --next \"...\" --important \"...\"\n\nturtle agents propose \\\n  --kind codex --session-id \u003Cid> --label \"...\" --cwd \u002Fabs\u002Fpath \\\n  [--branch main] [--resume-hint \"codex resume \u003Cid>\"]\n\nturtle external propose \\\n  --provider \u003Canything> --kind \u003Canything> --label \"...\" \\\n  [--url ...] [--environment production] \\\n  [--identifier KEY=VALUE]... [--config-path rel\u002Fpath]... [--tag t]... [--notes \"...\"]\n```\n\nAdd `--format json` to any of them to get the proposal ID and the exact record programmatically.\n\n### Provider and kind are free-form — use the real name\n\n`--provider` and `--kind` are plain data, not enums. An internal or obscure service is a\nfirst-class citizen and needs no new code. Write what the thing actually is\n(`--provider unfamiliar-service --kind widget-forge`), never a forced fit into a familiar vendor.\n\n### Confidence must be honest\n\n`--confidence confirmed|detected|suggested` (default `confirmed`).\n\nUse `confirmed` only for something the user stated or you read directly from a file. Use\n`detected` when you inferred it from evidence, `suggested` when you are guessing. **Never\nfabricate an identifier, URL, or account reference** — omit the flag instead. A wrong identifier\nin a bucket is worse than a missing one, because the user will trust it later.\n\n## What Turtle will refuse\n\nThese are enforced server-side and rejecting them is correct behavior, not a bug to route around:\n\n| Attempt | Error |\n|---|---|\n| Any credential, token, key, or password in any field | `secret_rejected`, with the exact JSON path |\n| A path outside the project's approved roots | `invalid_value` |\n| An unknown resource kind | rejected — `window`, `url`, `folder`, `file`, `terminal_cwd`, `documentation` only |\n\nNever try to store an API key, token, connection string with a password, cookie, `.env` value, or\nprovider auth file. Store the *reference* — the dashboard URL, the non-secret project ref, the\npath to the config file — never the secret itself. Do not read `.env` values; `.env.example`\nvariable *names* are acceptable.\n\n## Batching gotcha\n\nAccepting one proposal invalidates every other pending proposal **of the same record type**\n(`resource`, `external`, `agent`, `handoff`) because the target digest changes. They auto-refresh, and the\nuser re-accepts the same ID on a second pass — but if you queue five external resources at once,\nwarn the user that approval takes more than one round. Proposing one at a time is friendlier.\n\n## Not available yet\n\nDo not suggest these; they appear in the plan but are **not implemented**:\n\n- `turtle external open` — no CLI command opens an external resource (the desktop UI can open one,\n  the CLI cannot)\n- `turtle capture propose --json -` and `handoff propose --stdin` — no stdin proposal path\n- `--source agent:claude` — the CLI records every manual proposal as `manual`; agent provenance is\n  not yet distinguishable in the bucket\n- Window and browser-tab capture — nothing captures or restores a native window or a Firefox tab\n  yet; `restore run` opens folders, files, and URLs only, and reports every other stored kind as\n  `unsupported`\n\nIf the user asks for one of these, say plainly that it is not built yet rather than improvising a\nsubstitute.\n\n## The desktop UI\n\n`turtle app` runs the persistent turtle shell plus the runtime in one process. Clicking the turtle\n(or `Ctrl+Super+T`, once `scripts\u002Finstall-shortcut.sh` has been run) opens the window, where the\nuser can create a project (`N`), approve a folder (`F`), run detect (`D`), write the handoff\n(`H`), accept or dismiss each finding (`A` \u002F `X`), and resume the project (`R`). Any single local\nresource opens with `Enter`, and an agent row copies its resume command. The interface is dark\nthroughout; `~\u002F.config\u002Fturtle\u002Fstyle.css` overrides any token.\n\n`turtle show` raises that window from the command line. It only works while `turtle app` is\nrunning, and it is what the global shortcut invokes.\n\nYou can run `turtle show`, but never launch `turtle app` yourself — it is a long-lived graphical\nprocess the user owns.\n","# Turtle project buckets\n\nTurtle keeps everything needed to understand and resume a project — local resources, external\nservice references, working state, and safe context — in one private local bucket.\n\nYou can **read** any bucket and **propose** additions. You can never write one.\n\n## Before anything else: is the runtime up?\n\nThe CLI is a thin client over a Unix socket. Nothing works without the runtime.\n\n```bash\nturtle project list\n```\n\n- `runtime_unavailable` → nothing is running. Ask the user to start either `turtle app` (desktop\n  companion plus the runtime) or `turtle serve` (headless). **Do not start it yourself** — it is\n  the sole writer, and a second one would fight the first for the socket.\n- In this repository, use `.\u002Fscripts\u002Fturtle` instead of `turtle`.\n\n`turtle app` and `turtle serve` are mutually exclusive; `turtle app` already serves the socket, so\nevery command below works the same either way.\n\n`XDG_RUNTIME_DIR` must be set. Turtle deliberately has no `\u002Ftmp` fallback.\n\n## The one rule that matters\n\n**Proposals are yours. Decisions are the user's.**\n\nEvery write goes through a `CaptureProposal` that a human must approve. `turtle capture accept`\nrequires an interactive terminal *and* the user typing the exact proposal ID. Piped or scripted\nstdin is refused with `confirmation_required` and exit code 2.\n\nThis is not a limitation to work around. Never attempt to accept a proposal on the user's behalf,\nnever write bucket files directly, and never edit anything under the Turtle data root. Propose,\nthen show the user the proposal ID and let them accept.\n\n## Reading context\n\nStart here when you need to understand a project:\n\n```bash\nturtle context show                          # full bucket as Markdown\nturtle context show --format json            # same content, structured\nturtle context show --project \u003Cid-or-name>   # a project other than the selected one\n```\n\n`context show` returns everything at once: handoff, local resources, external resources, agents.\nPrefer it over assembling the narrower commands.\n\nNarrower reads:\n\n```bash\nturtle handoff show                # Current state \u002F Next \u002F Important\nturtle external list               # id, provider, kind, label, url\nturtle agents list                 # id, kind, label, cwd, resume hint\nturtle restore plan                # side-effect-free; prints actions, opens nothing\nturtle project list                # `*` marks the selected project\nturtle capture show \u003Cproposal-id>  # exactly what a pending proposal would store\nturtle status                      # is the runtime up, and what is installed\n```\n\n`restore plan` never opens or launches anything. It is safe to run.\n\n`turtle status` is the exception to the rule above: it is the one command that works with no\nruntime listening, so it is what to run when everything else answers `runtime_unavailable`.\n\n## Three things only the user may do\n\nThese change the user's machine directly and none of them goes through the proposal queue. Print\nthe command and let the user run it.\n\n```bash\nturtle here                         # this folder becomes a selected, scanned project\nturtle project add-root \u002Fabs\u002Fpath   # widens what Turtle is allowed to scan\nturtle restore run                  # actually opens folders, files, and URLs\n```\n\n`turtle here` is the fastest setup path — it selects or creates the project for a folder, approves\nthat folder, and scans it in one step — but it both creates a project and widens the scan scope, so\nit is the user's call. Suggest it when a project has no bucket yet.\n\n`project add-root` is the only way to approve a further folder for an existing project, and\napproving a root is what lets the collectors read it. Widening that scope is the user's call, not\nyours.\n\n`restore run` opens real windows on the user's desktop. Run it only when the user has asked for a\nrestore in that turn. It reports `opened` and `failed` per resource, never stops at the first\nfailure, and never closes anything. `--only \u003Cresource-id>` restores a single resource; get IDs\nfrom `turtle restore plan`.\n\n## Letting Turtle find things for itself\n\n```bash\nturtle inspect                      # scan approved roots, queue what is new\nturtle inspect --format json        # queued \u002F skipped \u002F failures\n```\n\nThe bundled collectors read the approved roots and propose a git remote as an external resource,\nthe repository root, README and manifests as local resources, and `.env.example` variable *names*\nonly. Everything they find is marked `detected`, never `confirmed`, and lands in the same review\nqueue as a manual proposal — **detection never stores anything**.\n\nOne more collector reads outside the roots, by design: it looks at the local Codex CLI's own\nsession headers and proposes an agent reference for any session whose working directory is inside\nan approved root. It reads the first line of a rollout file and nothing else, so no conversation\ncontent is ever read, and it degrades to a reported failure if Codex changes that format.\n\nFindings that already match a stored record come back under `skipped` with reason\n`already_stored`, one the user dismissed comes back as `dismissed` and is never re-offered, and a\nfinding still awaiting a decision is simply listed again — so running it repeatedly is safe and\nidempotent. The desktop window scans a project by itself whenever it is opened, so a finding you\nsee there may already be waiting without anyone having run `inspect`. Prefer `turtle inspect` over\nhand-writing proposals for anything a collector can find; it produces better provenance\n(`collector:git@1`) and real evidence.\n\n## Proposing\n\nAll proposal commands print a proposal ID and exit without changing the bucket.\n\n```bash\nturtle capture folder        --label \"Repo\"  --path \u002Fabs\u002Fpath\u002Finside\u002Fan\u002Fapproved\u002Froot\nturtle capture documentation --label \"Plan\"  --url https:\u002F\u002Fexample.com\u002Fplan\nturtle capture url           --label \"Board\" --url https:\u002F\u002Fexample.com\u002Fboard\n\nturtle handoff propose --current-state \"...\" --next \"...\" --important \"...\"\n\nturtle agents propose \\\n  --kind codex --session-id \u003Cid> --label \"...\" --cwd \u002Fabs\u002Fpath \\\n  [--branch main] [--resume-hint \"codex resume \u003Cid>\"]\n\nturtle external propose \\\n  --provider \u003Canything> --kind \u003Canything> --label \"...\" \\\n  [--url ...] [--environment production] \\\n  [--identifier KEY=VALUE]... [--config-path rel\u002Fpath]... [--tag t]... [--notes \"...\"]\n```\n\nAdd `--format json` to any of them to get the proposal ID and the exact record programmatically.\n\n### Provider and kind are free-form — use the real name\n\n`--provider` and `--kind` are plain data, not enums. An internal or obscure service is a\nfirst-class citizen and needs no new code. Write what the thing actually is\n(`--provider unfamiliar-service --kind widget-forge`), never a forced fit into a familiar vendor.\n\n### Confidence must be honest\n\n`--confidence confirmed|detected|suggested` (default `confirmed`).\n\nUse `confirmed` only for something the user stated or you read directly from a file. Use\n`detected` when you inferred it from evidence, `suggested` when you are guessing. **Never\nfabricate an identifier, URL, or account reference** — omit the flag instead. A wrong identifier\nin a bucket is worse than a missing one, because the user will trust it later.\n\n## What Turtle will refuse\n\nThese are enforced server-side and rejecting them is correct behavior, not a bug to route around:\n\n| Attempt | Error |\n|---|---|\n| Any credential, token, key, or password in any field | `secret_rejected`, with the exact JSON path |\n| A path outside the project's approved roots | `invalid_value` |\n| An unknown resource kind | rejected — `window`, `url`, `folder`, `file`, `terminal_cwd`, `documentation` only |\n\nNever try to store an API key, token, connection string with a password, cookie, `.env` value, or\nprovider auth file. Store the *reference* — the dashboard URL, the non-secret project ref, the\npath to the config file — never the secret itself. Do not read `.env` values; `.env.example`\nvariable *names* are acceptable.\n\n## Batching gotcha\n\nAccepting one proposal invalidates every other pending proposal **of the same record type**\n(`resource`, `external`, `agent`, `handoff`) because the target digest changes. They auto-refresh, and the\nuser re-accepts the same ID on a second pass — but if you queue five external resources at once,\nwarn the user that approval takes more than one round. Proposing one at a time is friendlier.\n\n## Not available yet\n\nDo not suggest these; they appear in the plan but are **not implemented**:\n\n- `turtle external open` — no CLI command opens an external resource (the desktop UI can open one,\n  the CLI cannot)\n- `turtle capture propose --json -` and `handoff propose --stdin` — no stdin proposal path\n- `--source agent:claude` — the CLI records every manual proposal as `manual`; agent provenance is\n  not yet distinguishable in the bucket\n- Window and browser-tab capture — nothing captures or restores a native window or a Firefox tab\n  yet; `restore run` opens folders, files, and URLs only, and reports every other stored kind as\n  `unsupported`\n\nIf the user asks for one of these, say plainly that it is not built yet rather than improvising a\nsubstitute.\n\n## The desktop UI\n\n`turtle app` runs the persistent turtle shell plus the runtime in one process. Clicking the turtle\n(or `Ctrl+Super+T`, once `scripts\u002Finstall-shortcut.sh` has been run) opens the window, where the\nuser can create a project (`N`), approve a folder (`F`), run detect (`D`), write the handoff\n(`H`), accept or dismiss each finding (`A` \u002F `X`), and resume the project (`R`). Any single local\nresource opens with `Enter`, and an agent row copies its resume command. The interface is dark\nthroughout; `~\u002F.config\u002Fturtle\u002Fstyle.css` overrides any token.\n\n`turtle show` raises that window from the command line. It only works while `turtle app` is\nrunning, and it is what the global shortcut invokes.\n\nYou can run `turtle show`, but never launch `turtle app` yourself — it is a long-lived graphical\nprocess the user owns.\n",{"name":5,"description":7},"main","db45f6d5ed859b8a05820115a0f79e7106254100",".claude\u002Fskills\u002Fturtle","https:\u002F\u002Fgithub.com\u002Fop-q\u002Fturtle","https:\u002F\u002Fgithub.com\u002Fop-q","2026-07-29 19:57:21",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add op-q\u002Fturtle --skill turtle",{"tool":36,"command":37},"bunx","bunx skills add op-q\u002Fturtle --skill turtle",{"tool":39,"command":40},"pnpm","pnpm dlx skills add op-q\u002Fturtle --skill turtle","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fop-q\u002Fturtle\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fturtle\u002FSKILL.md",true,[],[45],{"skillNo":46,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":47,"categories":48,"keywords":49,"publishedAt":19},"01M79RFJQ07YNY08SNGKRWR4W4","https:\u002F\u002Fgithub.com\u002Fop-q\u002Fturtle\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fturtle\u002FSKILL.md",[],[]]