From 06180dd934b15ff7cf7ba4bef280cd32a8307a60 Mon Sep 17 00:00:00 2001 From: oratis Date: Thu, 28 May 2026 14:27:40 +0800 Subject: [PATCH] chore: deepen remaining 11 SKILL.md + Dependabot + macOS in CI matrix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit · packages/core/skills/{run,consolidate-memory,fewer-permission-prompts, update-config,keybindings-help,deepseek-api,loop,schedule,review,pdf, skill-creator}/SKILL.md — Expanded each from 12-line stub to 40-90 line skill body. All 15 built-in skills now have real content (not just frontmatter). · .github/dependabot.yml (NEW) — weekly npm + github-actions updates; groups minor/patch by ecosystem (typescript, eslint, vitest, react) so the queue doesn't drown in tiny PRs. Major updates stay separate for explicit review. · .github/workflows/ci.yml — matrix [ubuntu, macos]. Lint now ENFORCED (was continue-on-error). Worktree tests gated behind DEEPCODE_WORKTREE_TESTS=1, run as a separate continue-on-error step. Tests: 471 still passing in default mode (424 + 47). Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/dependabot.yml | 51 ++++++++++++++ .github/workflows/ci.yml | 15 ++-- .../core/skills/consolidate-memory/SKILL.md | 31 +++++++- packages/core/skills/deepseek-api/SKILL.md | 70 ++++++++++++++++++- .../skills/fewer-permission-prompts/SKILL.md | 42 ++++++++++- .../core/skills/keybindings-help/SKILL.md | 49 ++++++++++++- packages/core/skills/loop/SKILL.md | 46 +++++++++++- packages/core/skills/pdf/SKILL.md | 46 +++++++++++- packages/core/skills/review/SKILL.md | 44 +++++++++++- packages/core/skills/run/SKILL.md | 26 ++++++- packages/core/skills/schedule/SKILL.md | 54 +++++++++++++- packages/core/skills/skill-creator/SKILL.md | 47 ++++++++++++- packages/core/skills/update-config/SKILL.md | 48 ++++++++++++- 13 files changed, 543 insertions(+), 26 deletions(-) create mode 100644 .github/dependabot.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..3f16b85 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,51 @@ +# Dependabot — auto PRs for dependency updates. +# Spec: docs/DEVELOPMENT_PLAN.md §0 (engineering hygiene) +# +# We group most updates by ecosystem so we don't drown in tiny PRs. Major +# updates remain separate so they get explicit review. + +version: 2 +updates: + - package-ecosystem: npm + directory: '/' + schedule: + interval: weekly + day: monday + open-pull-requests-limit: 5 + groups: + typescript: + patterns: + - 'typescript' + - '@types/*' + - 'typescript-eslint' + update-types: + - 'minor' + - 'patch' + eslint: + patterns: + - 'eslint' + - '@eslint/*' + update-types: + - 'minor' + - 'patch' + testing: + patterns: + - 'vitest' + - '@vitest/*' + update-types: + - 'minor' + - 'patch' + react: + patterns: + - 'react' + - 'react-dom' + - '@types/react' + - '@types/react-dom' + update-types: + - 'minor' + - 'patch' + + - package-ecosystem: github-actions + directory: '/' + schedule: + interval: weekly diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 09a9498..d5c53ee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,9 +12,13 @@ concurrency: jobs: check: - name: Typecheck + Lint + Test - runs-on: ubuntu-latest - timeout-minutes: 15 + name: Typecheck + Lint + Test (${{ matrix.os }}) + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest] + runs-on: ${{ matrix.os }} + timeout-minutes: 20 steps: - name: Checkout @@ -39,7 +43,10 @@ jobs: - name: Lint run: pnpm lint - continue-on-error: true # M0: lint 配置随 M1 完善，先不阻塞 + + - name: Worktree tests (gated) + run: DEEPCODE_WORKTREE_TESTS=1 pnpm -F @deepcode/core test src/worktree/ + continue-on-error: true # flaky cross-platform; not yet a blocker - name: Format check run: pnpm format:check diff --git a/packages/core/skills/consolidate-memory/SKILL.md b/packages/core/skills/consolidate-memory/SKILL.md index 54c4c63..48a364e 100644 --- a/packages/core/skills/consolidate-memory/SKILL.md +++ b/packages/core/skills/consolidate-memory/SKILL.md @@ -5,8 +5,35 @@ description: Walk ~/.deepcode/memory/, merge duplicates, prune the index. # consolidate-memory -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +DeepCode's `#` command appends snippets to the user's persistent memory. +Over time these accumulate duplicates and stale entries; this skill cleans +them up. ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User says "consolidate my memory", "clean up notes", "dedupe memory". +- User notices the same hint surfacing twice in successive sessions. + +## Process + +1. **Read all files** under `~/.deepcode/memory/` (one MD per topic). +2. **Group by similarity** — entries on the same topic / same fact. +3. **Merge duplicates** — keep the most recent, clearest phrasing. +4. **Prune stale** — if an entry references a removed file/dir or an + outdated CLI flag, suggest deletion (don't auto-delete). +5. **Update the index** — `~/.deepcode/memory/MEMORY.md` should still + reference every remaining file. Drop dead links. + +## Anti-patterns + +- Don't auto-delete anything — always show the proposed delete list and + wait for user approval. +- Don't merge entries that LOOK similar but encode different decisions + (e.g. "use pnpm" + "use yarn" — they aren't duplicates, they're a + conflict to flag). + +## Output + +A single proposed-changes block with each action: KEEP / MERGE → / DELETE / EDIT, +and a final summary `N files; M consolidated; K to delete`. Then ask the +user to approve before writing. diff --git a/packages/core/skills/deepseek-api/SKILL.md b/packages/core/skills/deepseek-api/SKILL.md index fa67145..ebd65e4 100644 --- a/packages/core/skills/deepseek-api/SKILL.md +++ b/packages/core/skills/deepseek-api/SKILL.md @@ -5,8 +5,74 @@ description: Help build/debug DeepSeek API usage (openai-compatible). # deepseek-api -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +DeepSeek's HTTP API is OpenAI-Compatible. Use the same patterns; just +swap the base URL and key. ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User asks "how do I call DeepSeek", "debug my chat completion call", + "stream tool calls from DeepSeek", etc. + +## Basics + +- **Base URL**: `https://api.deepseek.com/v1` +- **Auth**: `Authorization: Bearer ` (or set via env) +- **SDK**: any OpenAI-compatible SDK works; e.g. `openai` npm with + `baseURL: 'https://api.deepseek.com/v1'`. + +## Models + +| Model | Alias | Strengths | +| ------------------- | ------------------ | -------------------------------------- | +| `deepseek-chat` | → `deepseek-v4-flash` | Fast general chat; tool use | +| `deepseek-reasoner` | → `deepseek-v4-pro` | Multi-step reasoning; emits `reasoning_content` | + +Set via the standard `model` field. + +## Streaming + +Pass `stream: true`. SSE chunks come back as `data: {...}\n\n`. Each +chunk has `choices[0].delta.content` for text deltas, and +`choices[0].delta.tool_calls[]` for partial tool calls. + +`deepseek-reasoner` ALSO emits `choices[0].delta.reasoning_content` — +the thinking trace. UI should render this in a collapsible panel. + +## Tool calling + +Standard OpenAI shape: + +```js +const r = await client.chat.completions.create({ + model: 'deepseek-chat', + messages: [...], + tools: [{ + type: 'function', + function: { + name: 'Read', + description: '...', + parameters: { type: 'object', properties: {...}, required: [...] } + } + }], + tool_choice: 'auto', +}); +``` + +Response includes `choices[0].message.tool_calls[]` when the model +chose to call a tool. Loop: send back `role: 'tool'` messages with the +`tool_call_id`, get next assistant message, repeat until no tool calls. + +## Pricing (rough; verify on dashboard) + +| Tier | Input | Output | Reasoning | +| ------------ | ------ | ------ | --------- | +| deepseek-chat | 1¥/M | 2¥/M | — | +| deepseek-reasoner | 1¥/M | 16¥/M | 4¥/M | + +## Common pitfalls + +- **`temperature: 1.0` makes tool calls flaky** — drop to 0.3 for tool use. +- **Streaming + tool_use** — must accumulate tool args across chunks; the + args field comes in pieces. +- **`reasoning_content` is not in messages** — it's separate; don't try + to echo it back as a content block to the model. diff --git a/packages/core/skills/fewer-permission-prompts/SKILL.md b/packages/core/skills/fewer-permission-prompts/SKILL.md index dbf4317..9a73588 100644 --- a/packages/core/skills/fewer-permission-prompts/SKILL.md +++ b/packages/core/skills/fewer-permission-prompts/SKILL.md @@ -5,8 +5,46 @@ description: Scan transcripts, propose .deepcode/settings.json allow rules. # fewer-permission-prompts -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +The user keeps hitting the same approval prompt? Auto-generate a focused +`allow` rule from recent transcripts so they stop being asked. ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User says "stop asking", "auto-approve npm test", "I keep clicking yes". +- User explicitly runs `/fewer-permission-prompts`. + +## Process + +1. **Scan recent sessions** — `~/.deepcode/sessions/*.jsonl`, last 7 days. +2. **Collect approved tool calls** — every PreToolUse where the user said + yes. Bin by tool + leading arg (e.g. `Bash(npm test:*)`). +3. **Find recurring bins** — anything approved 3+ times. +4. **Propose rules** matching the existing permission rule syntax: + - `Bash(npm test:*)` for a subcommand pattern + - `Bash(npm test *)` for a prefix pattern + - `Read(/**)` for a path glob +5. **Show the user** the proposed additions to `.deepcode/settings.json` + (project-scoped). Wait for approval before writing. + +## Safety + +- Never propose `Bash(*)` or `Bash(rm:*)` — those are too broad. +- Never propose rules from `bypassPermissions` mode (the user wasn't + actually being asked). +- Default to PROJECT-scoped settings (`.deepcode/settings.json`) not user- + global (`~/.deepcode/settings.json`). Users can override. + +## Output + +A diff-like preview: + +``` +.deepcode/settings.json (proposed): + + permissions.allow: + + "Bash(npm test:*)" seen 14 times, last 2 days ago + + "Bash(git diff:*)" seen 9 times + + "Read(./src/**)" seen 47 times + +Apply? [y]es / [n]o / [e]dit +``` diff --git a/packages/core/skills/keybindings-help/SKILL.md b/packages/core/skills/keybindings-help/SKILL.md index f3cf07f..42cfc3c 100644 --- a/packages/core/skills/keybindings-help/SKILL.md +++ b/packages/core/skills/keybindings-help/SKILL.md @@ -5,8 +5,53 @@ description: Help edit ~/.deepcode/keybindings.json. # keybindings-help -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +Add or modify entries in `~/.deepcode/keybindings.json`. Explain the +syntax + show what will change. ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User says "bind X to Y", "add a shortcut", "enable Vim mode". +- User runs `/keybindings` and asks for a tweak. + +## File schema + +```json +{ + "enabled": true, + "vim": false, + "bindings": [ + { "key": "ctrl+shift+t", "action": "/clear" }, + { "key": "esc esc", "action": "/rewind" }, + { "key": "g g", "action": "cursor-buffer-start", "when": "NORMAL" } + ] +} +``` + +## Key chord syntax + +- Modifiers: `ctrl`, `shift`, `alt`, `meta`. +- Separator: `+` for chord (`ctrl+a`), space for sequence (`g g`). +- The order of modifiers is normalized, so `Shift+Ctrl+A` ≡ `ctrl+shift+a`. + +## Action forms + +1. **Slash command** — `"/clear"`, `"/mode plan"`, etc. +2. **Literal insertion** — `"insert:hello"` inserts "hello" at cursor. +3. **Built-in action** — `cursor-line-start`, `kill-to-end`, `vim-insert-mode`, etc. + +See `DEFAULT_KEYBINDINGS` in `packages/core/src/keybindings/index.ts` +for the full list. + +## Vim mode + +When `vim: true`, the `when` field constrains a binding to `NORMAL` / +`INSERT` / `VISUAL`. Vim defaults (i, a, v, gg, dd, yy, p, u) ship by +default; user bindings layer on top. + +## Process + +1. Read current file (or note it doesn't exist). +2. Validate the user's chord (must match `chord-syntax`). +3. Check for collisions with existing bindings — warn the user. +4. Show the diff, ask y/n/e. +5. Write back. diff --git a/packages/core/skills/loop/SKILL.md b/packages/core/skills/loop/SKILL.md index 9486f3b..f1523f4 100644 --- a/packages/core/skills/loop/SKILL.md +++ b/packages/core/skills/loop/SKILL.md @@ -5,8 +5,50 @@ description: Run a command on a recurring interval (poll CI etc.). # loop -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +Drive a polling loop where the agent re-checks state at an interval — +useful for "wait until CI is green", "poll deploy status", "tail a log". ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User says "watch", "poll", "every N seconds check X", "wait until Y". +- Long-running observation with a clear termination condition. + +## Pattern + +Use `ScheduleWakeup` (or the loop primitive in the host) with a sensible +delay: + +| Watching | Delay | Why | +| ------------------------- | ------------ | ------------------------------------ | +| CI run | 60-270 s | Status changes minute-scale | +| Deploy queue | 60-180 s | Same | +| Local file change | 5-30 s | Use fs.watch instead when possible | +| Cron / external timer | 20-30 min | Don't burn cache for nothing | +| "Idle tick, no signal" | 20-30 min | Default; cap notification noise | + +## Cache-aware delays + +Anthropic-style prompt caches expire after ~5 min. Pick either: +- **Under 5 min**: cache stays warm (60-270 s). +- **Long fallback**: 20+ min (one cache miss buys a long wait). + +Avoid 5-15 min windows — they pay the miss without amortizing. + +## Termination + +ALWAYS have a clear stop condition. Loop should exit when: +- The watched condition is met. +- The user issues an interrupt / says stop. +- A timeout cap is exceeded (refuse to infinite-loop). + +## Output per tick + +Just enough to confirm progress: `[14:32] CI status: in_progress (8/12 jobs)`. +Don't dump full logs each tick. + +## Anti-patterns + +- Polling every second (burns API budget; rarely needed). +- Infinite loop without a max-iterations cap. +- Polling instead of using the harness's notification mechanism — if the + runtime can wake you on the event, use that instead. diff --git a/packages/core/skills/pdf/SKILL.md b/packages/core/skills/pdf/SKILL.md index d7e70d1..e192ce4 100644 --- a/packages/core/skills/pdf/SKILL.md +++ b/packages/core/skills/pdf/SKILL.md @@ -5,8 +5,50 @@ description: Read/extract/combine/split PDFs. # pdf -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +Common PDF ops without bringing in a heavyweight Node dependency. Use +the OS-bundled tools (macOS) or `pdftk` (Linux) via Bash. ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User says "extract page X", "merge these PDFs", "summarize this PDF", + "remove page Y from foo.pdf". + +## Tools + +| Op | macOS | Linux (pdftk) | +| -------------------- | -------------------------------------------------- | ---------------------------------------------- | +| Extract pages 2-5 | `cpdf in.pdf 2-5 -o out.pdf` (needs cpdf) | `pdftk in.pdf cat 2-5 output out.pdf` | +| Merge a, b, c | (PDF Toolkit / cpdf) | `pdftk a.pdf b.pdf c.pdf cat output merged.pdf` | +| Split per page | `cpdf -split in.pdf -o page-%d.pdf` | `pdftk in.pdf burst output page-%02d.pdf` | +| Text dump | `pdftotext in.pdf -` (needs poppler) | same | +| Page count | `pdftk in.pdf dump_data | grep NumberOfPages` | same | + +If neither `cpdf` nor `pdftk` is installed, use Python + `pypdf` (one +dep, pure Python): + +```bash +python3 -c " +from pypdf import PdfReader, PdfWriter +r = PdfReader('in.pdf') +w = PdfWriter() +for p in r.pages[1:5]: # pages 2-5 (0-indexed) + w.add_page(p) +w.write(open('out.pdf', 'wb')) +" +``` + +## Reading content for the agent + +For summarization, extract text first, then feed it to the model. Use +`pdftotext in.pdf -` (poppler) which writes to stdout — easy to capture +in Bash output. + +If the PDF is scanned (image-only), text extraction returns empty/garbage. +Tell the user: "this PDF is scanned; you'd need OCR via tesseract first" +rather than producing nonsense. + +## Anti-patterns + +- Don't write a full Node PDF parser inline — use the CLI tool. +- Don't try to OCR scanned PDFs without explicitly opting in (slow + needs + the language pack). diff --git a/packages/core/skills/review/SKILL.md b/packages/core/skills/review/SKILL.md index 38a0afa..c9792c5 100644 --- a/packages/core/skills/review/SKILL.md +++ b/packages/core/skills/review/SKILL.md @@ -5,8 +5,48 @@ description: Review the current PR (uses gh CLI). # review -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +Review a GitHub pull request: pull the diff via `gh`, run `code-review` +checklist, post or summarize findings. ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User says "review PR #N", "look at this PR", "review my PR". +- User is on a feature branch and wants a check before pushing. + +## Process + +1. **Identify the PR**: + - Explicit `#N` → `gh pr view N --json title,body,baseRefName,headRefName`. + - "current branch" → `gh pr view --json ...` (detects from HEAD). +2. **Fetch the diff**: + - `gh pr diff ` (or `git diff ...HEAD` if local). +3. **Apply the `code-review` skill** — bug / latent / suggestion findings + with `file:line` cites. +4. **Apply `security-review` if** the diff touches auth / file paths / + exec / HTTP / serialization. +5. **Decide on output**: + - Local feedback → print to user. + - Post as PR comment → `gh pr comment --body "..."`. + - Post inline review → `gh api` with a review payload (advanced). + +## What NOT to do + +- Don't approve or merge — those require user action. +- Don't post findings without showing the user the draft first. +- Don't paraphrase the diff back at the user. Be specific about defects. + +## Output shape + +``` +Reviewing PR #42: "Add /init multi-phase flow" + + Found 3 issues: + + · BUG apps/cli/src/repl.ts:147 — initFlow promise resolves before file + write completes; user sees "OK" then file is half-written if Ctrl+C. + · TEST GAP apps/cli/src/headless.test.ts — no test for `--json-schema` + happy path; only error paths covered. + · STYLE apps/cli/src/commands.ts:222 — unused `_args`; drop the prefix. + + Verdict: changes-requested. Ready to push these to the PR comments? [y/n] +``` diff --git a/packages/core/skills/run/SKILL.md b/packages/core/skills/run/SKILL.md index 2f86cb6..e9ccc82 100644 --- a/packages/core/skills/run/SKILL.md +++ b/packages/core/skills/run/SKILL.md @@ -5,8 +5,30 @@ description: Launch this project's app to see a change in action. # run -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +Drive the project's own dev/test/build scripts. Detect toolchain from manifest. ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User says "run", "start dev server", "build", "run the tests". +- After making a code change, when the next step is to verify by execution. + +## Toolchain detection + +| Manifest | Typical commands | +| ---------------- | ------------------------------------------------------ | +| `package.json` | `pnpm dev` / `pnpm test` / `pnpm build` (or npm/yarn) | +| `pyproject.toml` | `pytest`, `uv run pytest`, `python -m ` | +| `Cargo.toml` | `cargo test`, `cargo run`, `cargo build --release` | +| `go.mod` | `go test ./...`, `go run ./cmd/` | +| `Gemfile` | `bundle exec rspec`, `bundle exec rails s` | +| `Makefile` | Prefer `make test` / `make dev` — usually canonical | + +Read `packageManager` in package.json (or `.tool-versions`) for the pinned +package manager — don't guess. + +## Output to report + +- Exit code +- The exact command run (so the user can re-execute) +- Summary parsed from the runner: `42 passed, 3 failed, 1 skipped`. +- File path of the first failure so the user can jump to it. diff --git a/packages/core/skills/schedule/SKILL.md b/packages/core/skills/schedule/SKILL.md index 7d61d7a..61fed16 100644 --- a/packages/core/skills/schedule/SKILL.md +++ b/packages/core/skills/schedule/SKILL.md @@ -5,8 +5,58 @@ description: Schedule a one-off or cron task via DeepCode's daemon. # schedule -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +Schedule background work via the `launchd` LaunchAgent (macOS) or its +Linux equivalent. Two common shapes: one-shot (run at time T) or +recurring (cron expression). ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User says "remind me at 5pm", "every day at 9am do X", "in 2 hours run Y". +- User wants automation that survives the current session. + +## Storage + +Tasks live in `~/.deepcode/scheduled-tasks.json`: + +```json +[ + { + "id": "task-abc", + "type": "oneshot", + "runAt": "2026-05-28T17:00:00Z", + "command": "deepcode -p 'check the build status' -o json" + }, + { + "id": "task-def", + "type": "cron", + "schedule": "0 9 * * *", + "command": "deepcode -p 'morning standup' -o text" + } +] +``` + +The `launchd` LaunchAgent (`dev.deepcode.scheduler`) fires every minute, +reads this file, and dispatches due tasks. + +## Process + +1. **Parse user intent** — extract type (oneshot/cron) and schedule. +2. **Build the command** — usually `deepcode -p ""` with the + user's task description. +3. **Append to the JSON** — generate a fresh ID, write atomically. +4. **Confirm** — show the user when it'll run + what it'll do. + +## Cron syntax + +Standard 5-field cron: `min hour day-of-month month day-of-week`. +Examples: +- `0 9 * * 1-5` — 9am weekdays +- `*/15 * * * *` — every 15 min +- `0 0 1 * *` — first of the month + +## Anti-patterns + +- Don't schedule destructive tasks without `--mode dontAsk` AND a clear + user confirmation in the same turn. +- Don't accept "every second" or sub-minute schedules — launchd's + granularity is the StartInterval (default 60s). diff --git a/packages/core/skills/skill-creator/SKILL.md b/packages/core/skills/skill-creator/SKILL.md index 128b995..f54018b 100644 --- a/packages/core/skills/skill-creator/SKILL.md +++ b/packages/core/skills/skill-creator/SKILL.md @@ -5,8 +5,51 @@ description: Help author a new skill — frontmatter + body + best-trigger descr # skill-creator -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +Bootstrap a new skill markdown file with the right shape. Most of the value +of a skill is in the `description` (it's what drives matching) — spend the +effort there. ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User says "create a skill for X", "add a skill", "I want a skill that does Y". + +## Where the file goes + +| Source | Loaded as | +| --------------------------------------- | -------------------------------------------- | +| `packages/core/skills//SKILL.md` | Built-in (ships with the package) | +| `~/.deepcode/skills//SKILL.md` | User-global | +| `/.deepcode/skills//SKILL.md` | Project-scoped | +| Plugin's `skills//SKILL.md` | Plugin-contributed | + +For user-authored skills, default to user-global. Suggest project-scoped +only when the skill is specifically about THIS project. + +## Frontmatter (required) + +```yaml +--- +name: kebab-case-name +description: One sentence. Mention the trigger condition + the output shape. +--- +``` + +The `description` is what the matcher sees. Make it concrete: + +- ✓ "Look up tests for a specific function name. Returns test file paths." +- ✗ "Help with tests." + +## Body sections (recommended) + +1. **When to invoke** — user phrasings that should trigger this. +2. **Process / steps** — numbered list. +3. **Heuristics / categories** — what to look for. +4. **Anti-patterns** — what NOT to do. +5. **Output shape** — what the agent's response should look like. + +## Tips + +- Keep it under 100 lines. Longer skills are harder to load + match. +- Use concrete examples, not generalities. +- Reference other skills by name when relevant (e.g. "see `verify` for + the test-running checklist"). diff --git a/packages/core/skills/update-config/SKILL.md b/packages/core/skills/update-config/SKILL.md index 2095a42..707a0af 100644 --- a/packages/core/skills/update-config/SKILL.md +++ b/packages/core/skills/update-config/SKILL.md @@ -5,8 +5,52 @@ description: Modify settings.json / hooks / permissions safely + explain trade-o # update-config -(M4 baseline — body authored as quick guidance; can be expanded by the user via `/skill edit` or directly editing this file.) +Edit DeepCode's `settings.json` files safely. Always show a diff first. ## When to invoke -The agent should invoke this skill when the user request matches the description. +- User says "change settings", "add a hook", "set the model to X", "lower + the effort tier". +- User asks for a setting they describe but can't name (e.g. "make it + more cautious" → bump permissions to ask-on-write). + +## The three layers + +| Layer | Path | Precedence (highest = last applied) | +| -------- | ------------------------------------------- | ----------------------------------- | +| User | `~/.deepcode/settings.json` | lowest | +| Project | `/.deepcode/settings.json` | middle | +| Local | `/.deepcode/settings.local.json` (git-ignored) | highest | + +When the user says "for this project", write to project-scoped. When +they say "everywhere", user-scoped. When secret-y (API keys, work-only +overrides), local. + +## Process + +1. **Read** the existing file (or note that it doesn't exist). +2. **Compute the merged diff** the user will see after the change. +3. **Explain trade-offs** — what they're trading off by enabling/disabling. + E.g. `bypassPermissions` mode: "faster, but the agent can write + anywhere without asking — only do this in a sandbox/worktree." +4. **Show a clear diff** and ask `[y]es / [n]o / [e]dit`. +5. **Write** with `JSON.stringify(obj, null, 2)` (matches existing style). + +## Common requests + +| User asks | Setting | +| ---------------------------------------- | -------------------------------------------------------------------- | +| "Don't ask me about reads" | `permissions.allow: ["Read"]` | +| "Stop running tests for me" | `permissions.deny: ["Bash(npm test:*)"]` | +| "Use deepseek-reasoner by default" | `model: "deepseek-reasoner"` | +| "Lower the effort" | `effortLevel: "low"` | +| "Turn off the sandbox" | `sandbox.enabled: false` | +| "Disable plugin X" | `disabledPlugins: ["X"]` | +| "Add a hook to lint after edits" | `hooks.PostToolUse: [{ matcher: "Edit|Write", hooks: [...] }]` | + +## Refuse + +Don't: +- Delete `permissions.deny` rules without explicit confirmation. +- Write `apiKeyHelper` that points at a script you didn't author. +- Enable `bypassPermissions` as a default — it has to be a deliberate user act.