From fd16a433fb304584c39f971ed6b04bcc4c1c707e Mon Sep 17 00:00:00 2001 From: Xi Xu Date: Fri, 27 Mar 2026 16:49:33 +0800 Subject: [PATCH] chore: add bun formatting workflows --- .github/workflows/format-check.yml | 29 +++++++++++++++ .github/workflows/format-fix.yml | 48 ++++++++++++++++++++++++ .gitignore | 1 + .prettierignore | 1 + .prettierrc.json | 4 ++ AGENTS.md | 20 +++++----- MANIFEST_POLICY.md | 60 +++++++++++++++++++----------- README.md | 17 +++++++++ README.zh.md | 17 +++++++++ bun.lock | 15 ++++++++ package.json | 13 +++++++ skvlt.yaml | 23 +++++++----- 12 files changed, 208 insertions(+), 40 deletions(-) create mode 100644 .github/workflows/format-check.yml create mode 100644 .github/workflows/format-fix.yml create mode 100644 .gitignore create mode 100644 .prettierignore create mode 100644 .prettierrc.json create mode 100644 bun.lock create mode 100644 package.json diff --git a/.github/workflows/format-check.yml b/.github/workflows/format-check.yml new file mode 100644 index 0000000..aa88c9d --- /dev/null +++ b/.github/workflows/format-check.yml @@ -0,0 +1,29 @@ +name: Format Check + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +jobs: + prettier: + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v6 + + - name: Set up Bun + uses: oven-sh/setup-bun@v2.2.0 + with: + bun-version: 1.3.11 + + - name: Install dependencies + run: bun install --frozen-lockfile + + - name: Verify formatting + run: bun run format:check diff --git a/.github/workflows/format-fix.yml b/.github/workflows/format-fix.yml new file mode 100644 index 0000000..fb8fe47 --- /dev/null +++ b/.github/workflows/format-fix.yml @@ -0,0 +1,48 @@ +name: Format Fix + +on: + workflow_dispatch: + +permissions: + contents: write + +jobs: + prettier: + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v6 + + - name: Ensure the selected ref is a branch + shell: bash + run: | + if [[ "${GITHUB_REF_TYPE}" != "branch" ]]; then + echo "Format Fix must be run against a branch ref." + exit 1 + fi + + - name: Set up Bun + uses: oven-sh/setup-bun@v2.2.0 + with: + bun-version: 1.3.11 + + - name: Install dependencies + run: bun install --frozen-lockfile + + - name: Apply formatting + run: bun run format + + - name: Commit formatting changes + shell: bash + run: | + if git diff --quiet; then + echo "No formatting changes to commit." + exit 0 + fi + + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add . + git commit -m "chore: apply formatting" + git push diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c2658d7 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules/ diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..c2658d7 --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +node_modules/ diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..2530981 --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,4 @@ +{ + "endOfLine": "lf", + "proseWrap": "preserve" +} diff --git a/AGENTS.md b/AGENTS.md index 3d60fc7..e45cc46 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,12 +8,16 @@ The primary artifact is `skvlt.yaml`, which tracks approved skill sources, insta The main companion document is `MANIFEST_POLICY.md`, which defines how agents should decide whether to add, replace, reject, or escalate manifest changes. -There is currently no application code, package manager, build pipeline, or automated test suite checked into this repository. +There is currently no application code or automated test suite checked into this repository, but there is now a lightweight bun-based formatting toolchain and GitHub Actions formatting workflows. ## Repository Layout - `skvlt.yaml` - source-of-truth manifest for installed skills - `MANIFEST_POLICY.md` - maintenance policy for agent-driven manifest changes +- `package.json` - local formatter entrypoint and scripts +- `.prettierrc.json` - repository formatting rules +- `.github/workflows/format-check.yml` - formatting validation workflow +- `.github/workflows/format-fix.yml` - manual formatting remediation workflow - `LICENSE` - repository license ## Working Rules @@ -44,30 +48,28 @@ Follow `MANIFEST_POLICY.md` before making substantive manifest changes. High-level defaults: - Add specialized or dependency-closing skills only when they fit an already trusted source. -- Replace only when two general skills substantially overlap and the replacement is clearly better maintained or more authoritative. +- When two general skills substantially overlap, prefer the one that is more complete, more practical, and more worth retaining; use maintenance and authority as tie-breakers rather than the primary decision rule. - Reject skills that are tightly bound to a specific agent, repository, or runtime unless explicitly approved. -- Escalate ambiguous overlap, process-shaping changes, or source-level churn to a human. +- Escalate ambiguous overlap, close calls between broad general skills, process-shaping changes, or source-level churn to a human. ## Validation -There is no dedicated validation script in this repository today. - Before claiming a manifest edit is complete, verify: +- repository formatting still passes - the YAML remains readable - the manifest counts are internally consistent - the edited source block count matches the listed skills - any dependency-based addition is actually justified by installed skills or policy -Useful manual checks in PowerShell: +Useful local checks: ```powershell -Get-Content -Raw skvlt.yaml +bun install ``` ```powershell -$lines = Get-Content skvlt.yaml -$lines +bun run format:check ``` If you need upstream skill discovery, prefer checking the local installed skill files first, then use the relevant skills tooling or trusted upstream listing. diff --git a/MANIFEST_POLICY.md b/MANIFEST_POLICY.md index e04f4c9..d649361 100644 --- a/MANIFEST_POLICY.md +++ b/MANIFEST_POLICY.md @@ -9,7 +9,7 @@ It covers four outcomes: - rejection - escalation to humans -The policy is intentionally conservative because the manifest is global. A bad addition creates trigger noise everywhere, not just in one repository. +The policy is intentionally conservative because the manifest is global. A bad addition creates global maintenance cost, trigger noise, and weaker default skill selection. The goal is not merely to minimize overlap, but to keep the most complete, practical, and worth-retaining skills in each category. ## Audience @@ -50,6 +50,9 @@ Extracts: - source repository - skill name - trigger description +- documentation completeness signal +- practical utility signal +- depth or breadth of reusable guidance - explicit prerequisites - references to a specific agent, repository, or runtime - dependency skills @@ -76,8 +79,10 @@ Compares a candidate against installed skills in the same category. Its job is to answer: - Is this a general skill or a specialized skill? +- Which skill is more complete, practical, and worth retaining if only one remains? - Does it substantially overlap an installed skill's trigger scope? - If there is overlap, is it "general vs. general" or "general vs. specialized"? +- Does the overlap create redundant surface area, or does it add meaningful complementary depth? - Does it introduce new constraints that make it less portable? ### Decision Agent @@ -101,27 +106,33 @@ Approves only escalated changes or batched high-impact changes. ### 1. Conservative Global Bias -`skvlt.yaml` is a global manifest. The default should be to avoid broad, noisy, or brittle skills unless they add clear value. +`skvlt.yaml` is a global manifest. The default should be to avoid broad, noisy, or brittle skills unless they add clear value. However, reducing noise is a secondary constraint after choosing the skill that is strongest to keep long-term within its category. -### 2. Trigger Overlap Matters +### 2. Retention Value First -Substantial similarity of task triggers means two skills occupy the same task category without a real capability distinction. Those should be treated as overlapping. +When comparing skills in the same category, first ask which one is more complete, more practical, and more worth retaining for repeated real-world use. -### 3. General and Specialized Can Coexist +Completeness and practical utility should outrank superficial trigger neatness. If one skill is materially better as a lasting default, that matters more than preserving a narrower trigger boundary. + +### 3. Trigger Overlap Matters + +Substantial similarity of task triggers means two skills occupy the same task category without a real capability distinction. Overlap should be judged after content quality and retention value are assessed, not before. + +### 4. General and Specialized Can Coexist Do not force a trade-off between a broad general skill and a clearly narrower specialized skill. Trade-offs are required only when the comparison is effectively "general vs. general". -### 4. Trust and Maintenance Break Ties +### 5. Trust and Maintenance Break Ties -When trigger scope is the same, prefer: +When quality and practical value are otherwise close, prefer: - official or domain-relevant authors - repositories with strong installation counts - active maintenance -### 5. Dependencies Must Close +### 6. Dependencies Must Close A skill should not be auto-added if it depends on another skill that is missing from the manifest, unless the same change adds the dependency or a human approves an exception. @@ -154,9 +165,9 @@ Return `add` only when all of the following are true: - the candidate survives hard exclusion - its task category is already allowed in the manifest -- it is either specialized or genuinely non-overlapping +- it is either specialized, genuinely non-overlapping, or clearly complementary after comparing retention value against incumbents - its dependencies close cleanly -- it does not introduce broad trigger ambiguity +- it does not introduce broad trigger ambiguity without enough added practical value to justify coexistence Typical examples: @@ -168,9 +179,10 @@ Typical examples: Return `replace` only when all of the following are true: - the candidate and incumbent are both general skills -- their trigger scopes are substantially similar +- their trigger scopes are substantially similar enough that keeping both mostly duplicates maintenance surface area +- the candidate is clearly more complete, practical, and worth retaining for repeated use - the candidate is at least as portable as the incumbent -- the candidate wins clearly on trust and maintenance signals +- trust and maintenance signals do not materially undercut the candidate - there is no meaningful capability loss Replacement should not be used for "general vs. specialized" comparisons. @@ -180,10 +192,10 @@ Replacement should not be used for "general vs. specialized" comparisons. Return `reject` when any of the following is true: - the skill is bound to a specific agent, repository, or runtime -- it is a weaker duplicate of an installed general skill +- it is a weaker or lower-retention-value duplicate of an installed general skill - it creates dependency debt -- it adds noise without adding distinct capability -- it loses a tie-break on trust and maintenance +- it adds noise without enough incremental practical value +- it loses on completeness, practicality, and retention value, with trust and maintenance unable to reverse that judgment ### Escalation @@ -192,10 +204,11 @@ Return `escalate` when the case is not safely automatable. Escalation is required when: - the overlap judgment depends on interpretation rather than clear capability boundaries +- the completeness or practical-utility comparison is close rather than clear - the change adds a brand-new source block - the change removes the last skill from a source block - the candidate introduces external auth, paid APIs, or unusual runtime assumptions -- official-status and install-count signals disagree +- content quality and trust signals point in different directions - the skill shapes broad workflow behavior across many tasks ## Scoring Rubric @@ -204,6 +217,7 @@ Use the scoring rubric only after the hard exclusion pass. ### Positive Signals +- `+4` clearly more complete and practical than the incumbent in the same category - `+3` clear specialization with distinct capability - `+2` official or strongly domain-relevant author - `+2` active maintenance @@ -213,6 +227,7 @@ Use the scoring rubric only after the hard exclusion pass. ### Negative Signals +- `-4` shallower, less actionable, or less worth retaining than an incumbent - `-3` vague or noisy trigger wording - `-3` external service requirement that is not already normal for the manifest - `-4` missing dependency @@ -224,11 +239,11 @@ Use the scoring rubric only after the hard exclusion pass. ### Decision Bands -- `score >= 5`: eligible for `add` if no overlap concerns remain +- `score >= 5`: eligible for `add` if overlap review still shows clear incremental retention value - `score 2 to 4`: prefer `escalate` - `score <= 1`: prefer `reject` -For `replace`, compare candidate score against incumbent score. Auto-replace only when the candidate is ahead by at least `3` points and no escalation condition is present. +For `replace`, compare candidate score against incumbent score. Auto-replace only when the candidate is ahead by at least `3` points, clearly ahead on completeness and practical value, and no escalation condition is present. ## Human Escalation Packet @@ -238,6 +253,7 @@ When escalation is required, provide a short packet with: - source repository - task category - incumbent skill, if any +- completeness and practical utility comparison - overlap summary - binding and dependency notes - trust and maintenance comparison @@ -263,14 +279,14 @@ Treat these classes differently: - adding a skill to an existing trusted source - adding a missing dependency that is already referenced by installed skills -- replacing a low-trust general skill with a clearly better general skill +- replacing a lower-value general skill with a clearly more complete and practical general skill ### Must Escalate - new source added - source removed - process-shaping skill added, removed, or replaced -- ambiguous overlap between two broad general skills +- ambiguous overlap between two broad general skills with close retention value - any change that would alter maintenance policy itself ## Recommended Cadence @@ -316,6 +332,8 @@ For the current `skvlt.yaml`: - broad workflow skills should be treated as high-impact - source-level edits should escalate more readily than skill-level edits +- when two broad general skills overlap, first ask which one would still be worth keeping if only one remained +- prefer the skill that is more complete, more practical, and more worth retaining long-term; use trigger noise, authority, and maintenance as secondary constraints - dependency-completion additions inside an existing trusted source can be auto-approved -This means a change like "add a missing dependency skill under an existing source" is lower risk than "replace a broad browser automation skill family" or "swap out a process-shaping skill". +This means a change like "add a missing dependency skill under an existing source" is lower risk than "replace a broad browser automation skill family", but for overlapping general skills the primary question should be retention value rather than trigger neatness alone. diff --git a/README.md b/README.md index b0df666..4fc0a7f 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,23 @@ This repository is not a standalone installer. Its role is to provide a maintain > [!IMPORTANT] > This repository is meant to be used with Skills Vault. Standalone use outside the Skills Vault workflow is not considered a supported primary workflow. +## Formatting + +This repository now includes a lightweight Prettier-based formatting toolchain for Markdown and YAML files. + +Local commands: + +```bash +bun install +bun run format:check +bun run format +``` + +GitHub Actions workflows: + +- `Format Check`: runs formatting validation on pull requests and pushes to `main` +- `Format Fix`: manual `workflow_dispatch` workflow that formats the selected branch and pushes a `chore: apply formatting` commit only when changes are needed + ## Change Policy Because this manifest is global rather than project-specific, changes are handled conservatively. diff --git a/README.zh.md b/README.zh.md index 8324096..0a5a4d0 100644 --- a/README.zh.md +++ b/README.zh.md @@ -69,6 +69,23 @@ bunx skvlt restore --all > [!IMPORTANT] > 本存储库只能配合 Skills Vault 使用。不支持脱离 Skills Vault 的独立使用方式，也不将临时手工使用视为正式工作流。 +## 格式化 + +本存储库现在包含一套基于 Prettier 的轻量格式化工具链，用于统一 Markdown 和 YAML 文件格式。 + +本地常用命令： + +```bash +bun install +bun run format:check +bun run format +``` + +GitHub Actions 工作流： + +- `Format Check`：在 `pull_request` 和推送到 `main` 时校验格式 +- `Format Fix`：手动触发 `workflow_dispatch` 后，对所选分支执行格式化；只有存在变更时才会自动提交 `chore: apply formatting` + ## 变更策略 由于这份清单面向的是全局 skills 集合，而不是单个项目，所以这里对变更采取保守策略。 diff --git a/bun.lock b/bun.lock new file mode 100644 index 0000000..ccc847e --- /dev/null +++ b/bun.lock @@ -0,0 +1,15 @@ +{ + "lockfileVersion": 1, + "configVersion": 1, + "workspaces": { + "": { + "name": "skvlt", + "devDependencies": { + "prettier": "3.8.1", + }, + }, + }, + "packages": { + "prettier": ["prettier@3.8.1", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg=="], + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..95336e0 --- /dev/null +++ b/package.json @@ -0,0 +1,13 @@ +{ + "name": "skvlt", + "private": false, + "license": "MIT", + "packageManager": "bun@1.3.11", + "scripts": { + "format": "prettier --write .", + "format:check": "prettier --check ." + }, + "devDependencies": { + "prettier": "3.8.1" + } +} diff --git a/skvlt.yaml b/skvlt.yaml index db7f129..1de2739 100644 --- a/skvlt.yaml +++ b/skvlt.yaml @@ -1,6 +1,6 @@ # Generated by Skills Vault: https://github.com/xixu-me/skills-vault total_sources: 21 -total_skills: 137 +total_skills: 140 scope: "global" sources: @@ -25,20 +25,20 @@ sources: - "humanizer" "callstackincubator/agent-skills": - count: 5 + count: 4 skills: - "github" - - "react-native-best-practices" - "react-native-brownfield-migration" - "upgrading-react-native" - "validate-skills" "chromedevtools/chrome-devtools-mcp": - count: 4 + count: 5 skills: - "a11y-debugging" - "chrome-devtools" - "debug-optimize-lcp" + - "memory-leak-debugging" - "troubleshooting" "cloudflare/skills": @@ -106,11 +106,6 @@ sources: - "langgraph-human-in-the-loop" - "langgraph-persistence" - "makenotion/skills": - count: 1 - skills: - - "notion-cli" - "obra/superpowers": count: 14 skills: @@ -208,13 +203,21 @@ sources: - "electron" "vercel-labs/agent-skills": - count: 4 + count: 5 skills: - "deploy-to-vercel" - "vercel-composition-patterns" - "vercel-react-best-practices" + - "vercel-react-native-skills" - "web-design-guidelines" + "xixu-me/skills": + count: 3 + skills: + - "github-actions-docs" + - "opensource-guide-coach" + - "skills-cli" + "xixu-me/xdrop": count: 1 skills: