From b9304e01d5d925f9d68864a6c965fa268cba8430 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 13 Oct 2026 21:02:44 +0800 Subject: [PATCH] docs(skills): remove the stale codebase-audit project skill The skill restated the audit topic in an older form: its flag grep matches no file because the CLI parses its own arguments, and its fixed list of mutating commands contradicts the topic's rule to judge from current behavior. The audit topic stays the source for consistency audits. The contributor page listed it, so it now lists skillshare-code-review in its place, and uses the skills' real names, which gained the skillshare- prefix in an earlier rename. --- .../skills/skillshare-codebase-audit/SKILL.md | 178 ------------------ website/docs/learn/with-ai-coding-agents.md | 20 +- .../current/learn/with-ai-coding-agents.md | 20 +- .../current/learn/with-ai-coding-agents.md | 20 +- .../current/learn/with-ai-coding-agents.md | 20 +- .../current/learn/with-ai-coding-agents.md | 20 +- 6 files changed, 50 insertions(+), 228 deletions(-) delete mode 100644 .skillshare/skills/skillshare-codebase-audit/SKILL.md diff --git a/.skillshare/skills/skillshare-codebase-audit/SKILL.md b/.skillshare/skills/skillshare-codebase-audit/SKILL.md deleted file mode 100644 index 4f3e52a1d..000000000 --- a/.skillshare/skills/skillshare-codebase-audit/SKILL.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -name: skillshare-codebase-audit -description: >- - Cross-validate CLI flags, docs, tests, and targets for consistency across the - codebase. Use this skill whenever the user asks to: audit the codebase, check - for consistency issues, find undocumented flags, verify test coverage, validate - targets.yaml, check handler split conventions, or verify oplog instrumentation. - This is a read-only audit — it reports issues but never modifies files. Use - after large refactors, before releases, or whenever you suspect docs/code/tests - have drifted out of sync. -metadata: - targets: [claude, universal] ---- - -Read-only consistency audit across the skillshare codebase. $ARGUMENTS specifies focus area (e.g., "flags", "tests", "targets") or omit for full audit. - -**Scope**: This skill only READS and REPORTS. It does not modify any files. Use `implement-feature` to fix issues or `update-docs` to fix documentation gaps. - -Before acting, run `python3 scripts/ai-context.py audit`. That topic is the source of truth for audit dimensions, evidence requirements and status meanings; this skill retains the search and report workflow. - -## Audit Dimensions - -Run every dimension below in parallel where possible. For each, produce a summary table. - -### 1. CLI Flag Audit - -Compare every flag defined in `cmd/skillshare/*.go` against `website/docs/reference/commands/*.md`. - -```bash -# Find all flags in Go source -grep -rn 'flag\.\(String\|Bool\|Int\)' cmd/skillshare/ -grep -rn 'Args\|Usage' cmd/skillshare/ -``` - -Report: -- **UNDOCUMENTED**: Flag exists in code but not in docs -- **STALE**: Flag documented but not found in code -- **OK**: Flag matches between code and docs - -### 2. Test Coverage - -For each command handler in `cmd/skillshare/.go`: -- Check if `tests/integration/_test.go` exists -- Check if key behaviors have test cases - -```bash -# List all command handlers -ls cmd/skillshare/*.go | grep -v '_test.go\|main.go\|helpers.go\|mode.go' - -# List all integration tests -ls tests/integration/*_test.go -``` - -Report: -- **COVERED**: Command has integration test file with test cases -- **PARTIAL**: Test file exists but missing key scenarios -- **MISSING**: No integration test for this command - -### 3. Target Audit - -Verify `internal/config/targets.yaml` entries: -- Each target has `skills.global` and `skills.project` -- Aliases are consistent -- No duplicate entries - -Report: -- **OK**: Target entry complete and valid -- **INCOMPLETE**: Missing required fields -- **DUPLICATE**: Name or alias collision - -### 4. Handler Split Audit - -For commands with >300 lines in `cmd/skillshare/.go`, verify the handler split convention is followed: - -```bash -# Find large command files -wc -l cmd/skillshare/*.go | sort -rn | head -20 -``` - -Check that large commands are properly split: - -| Suffix | Expected for large commands | -|--------|---------------------------| -| `_handlers.go` | Core logic extracted | -| `_render.go` | Output rendering separated | -| `_tui.go` | TUI components isolated | - -Report: -- **SPLIT**: Large command properly follows handler split convention -- **MONOLITH**: >300 lines without split (should be refactored) -- **N/A**: Small command, no split needed - -### 5. Oplog Coverage - -Verify all mutating commands have oplog instrumentation: - -```bash -# Find commands that modify state -grep -rn 'func handle\|func cmd' cmd/skillshare/*.go - -# Check for oplog.Write calls -grep -rn 'oplog.Write' cmd/skillshare/ -``` - -Mutating commands (install, uninstall, sync, update, init, collect, backup, restore, trash) should all write to oplog. Read-only commands (list, status, check, search, audit, log, version) should not. - -Report: -- **INSTRUMENTED**: Mutating command has oplog.Write -- **MISSING**: Mutating command lacks oplog instrumentation -- **N/A**: Read-only command (no oplog expected) - -### 6. Web API Consistency - -Verify `internal/server/handler_*.go` routes match CLI commands: - -```bash -# List all handler files -ls internal/server/handler_*.go | grep -v _test.go - -# Check route registration in server.go -grep -n 'HandleFunc\|Handle(' internal/server/server.go -``` - -Report: -- **SYNCED**: CLI command has corresponding API handler -- **CLI-ONLY**: Command exists in CLI but not in Web API (may be intentional) -- **API-ONLY**: API handler without CLI counterpart (unusual) - -## Output Format - -``` -== Skillshare Codebase Audit == - -### CLI Flags (N issues) -| Command | Flag | Status | -|-----------|-------------|--------------| -| install | --force | OK | -| install | --into | UNDOCUMENTED | - -### Test Coverage (N issues) -| Command | Status | Notes | -|-----------|---------|--------------------| -| sync | COVERED | | -| audit | PARTIAL | missing edge cases | -| target | MISSING | | - -### Targets (N issues) -| Target | Status | Notes | -|-----------|------------|---------------| -| claude | OK | | -| newagent | INCOMPLETE | no skills.project | - -### Handler Split (N issues) -| Command | Lines | Status | Notes | -|-----------|-------|-----------|--------------------| -| install | 450 | SPLIT | 6 sub-files | -| audit | 320 | MONOLITH | should split render | -| status | 80 | N/A | | - -### Oplog (N issues) -| Command | Mutating? | Status | -|-----------|-----------|---------------| -| install | Yes | INSTRUMENTED | -| trash | Yes | MISSING | -| list | No | N/A | - -### Web API (N issues) -| Command | CLI | API | Status | -|-----------|-----|-----|----------| -| install | Yes | Yes | SYNCED | -| diff | Yes | No | CLI-ONLY | - -== Summary: X OK / Y issues found == -``` - -## Rules - -Apply the `audit` topic and keep this workflow read-only. diff --git a/website/docs/learn/with-ai-coding-agents.md b/website/docs/learn/with-ai-coding-agents.md index a39ce9366..8f6ae8c04 100644 --- a/website/docs/learn/with-ai-coding-agents.md +++ b/website/docs/learn/with-ai-coding-agents.md @@ -25,19 +25,19 @@ Your AI agent now has access to specialized skills for working on this codebase. | Skill | What it does | |-------|-------------| -| `implement-feature` | Implement a feature from a spec file or description using TDD workflow | -| `update-docs` | Update website docs to match recent code changes, cross-validating every flag against source | -| `codebase-audit` | Cross-validate CLI flags, docs, tests, and targets for consistency across the codebase | -| `cli-e2e-test` | Run isolated E2E tests in devcontainer from runbooks | -| `changelog` | Generate a CHANGELOG.md entry from recent commits in conventional format | +| `skillshare-implement-feature` | Implement a feature from a spec file or description using TDD workflow | +| `skillshare-update-docs` | Update website docs to match recent code changes, cross-validating every flag against source | +| `skillshare-code-review` | Review a change in parallel passes (correctness, repo rules, spec, consumers, cleanup) and verify each finding | +| `skillshare-cli-e2e-test` | Run isolated E2E tests in devcontainer from runbooks | +| `skillshare-changelog` | Generate a CHANGELOG.md entry from recent commits in conventional format | ## Typical Workflow -1. **Start a feature** — ask your agent to use `implement-feature` with a spec -2. **Update docs** — after code changes, invoke `update-docs` to sync website docs -3. **Audit consistency** — run `codebase-audit` to catch flag/doc mismatches -4. **Run E2E tests** — use `cli-e2e-test` to verify in a sandbox -5. **Write changelog** — invoke `changelog` before release +1. **Start a feature** — ask your agent to use `skillshare-implement-feature` with a spec +2. **Update docs** — after code changes, invoke `skillshare-update-docs` to sync website docs +3. **Review the change** — run `skillshare-code-review` before committing or opening a PR +4. **Run E2E tests** — use `skillshare-cli-e2e-test` to verify in a sandbox +5. **Write changelog** — invoke `skillshare-changelog` before release ## What's Next? diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md index 0c319ee95..95175e426 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md @@ -26,19 +26,19 @@ skillshare sync -p | Skill | 何をするか | |-------|-------------| -| `implement-feature` | TDD ワークフローを使い、spec ファイルまたは説明から機能を実装する | -| `update-docs` | すべてのフラグを Source と照合しながら、Web サイトのドキュメントを最近のコード変更に合わせて更新する | -| `codebase-audit` | CLI フラグ、ドキュメント、テスト、Target をコードベース全体で相互検証する | -| `cli-e2e-test` | runbook から devcontainer 内で隔離された E2E テストを実行する | -| `changelog` | 最近のコミットから conventional な形式で CHANGELOG.md のエントリを生成する | +| `skillshare-implement-feature` | TDD ワークフローを使い、spec ファイルまたは説明から機能を実装する | +| `skillshare-update-docs` | すべてのフラグを Source と照合しながら、Web サイトのドキュメントを最近のコード変更に合わせて更新する | +| `skillshare-code-review` | 変更を並列パス(正確性、リポジトリのルール、仕様、利用箇所、クリーンアップ)でレビューし、各指摘を検証する | +| `skillshare-cli-e2e-test` | runbook から devcontainer 内で隔離された E2E テストを実行する | +| `skillshare-changelog` | 最近のコミットから conventional な形式で CHANGELOG.md のエントリを生成する | ## 典型的なワークフロー -1. **機能を始める** — Agent に spec を使って `implement-feature` を使うよう依頼する -2. **ドキュメントを更新する** — コード変更後、`update-docs` を呼び出して Web サイトのドキュメントを Sync する -3. **一貫性を監査する** — フラグ/ドキュメントの不一致を捕捉するために `codebase-audit` を実行する -4. **E2E テストを実行する** — サンドボックスで検証するために `cli-e2e-test` を使う -5. **changelog を書く** — リリース前に `changelog` を呼び出す +1. **機能を始める** — Agent に spec を使って `skillshare-implement-feature` を使うよう依頼する +2. **ドキュメントを更新する** — コード変更後、`skillshare-update-docs` を呼び出して Web サイトのドキュメントを Sync する +3. **変更をレビューする** — コミットや PR の前に `skillshare-code-review` を実行する +4. **E2E テストを実行する** — サンドボックスで検証するために `skillshare-cli-e2e-test` を使う +5. **changelog を書く** — リリース前に `skillshare-changelog` を呼び出す ## 次のステップ diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md index 03185cf01..903f76444 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md @@ -24,19 +24,19 @@ skillshare sync -p | Skill | 하는 일 | |-------|-------------| -| `implement-feature` | TDD 워크플로를 사용해 spec 파일이나 설명으로부터 기능을 구현합니다 | -| `update-docs` | 모든 플래그를 소스와 교차 검증하며 최근 코드 변경 사항에 맞춰 웹사이트 문서를 업데이트합니다 | -| `codebase-audit` | 코드베이스 전반에서 CLI 플래그, 문서, 테스트, Target의 일관성을 교차 검증합니다 | -| `cli-e2e-test` | Runbook을 기반으로 devcontainer에서 격리된 E2E 테스트를 실행합니다 | -| `changelog` | 최근 커밋으로부터 conventional 형식의 CHANGELOG.md 항목을 생성합니다 | +| `skillshare-implement-feature` | TDD 워크플로를 사용해 spec 파일이나 설명으로부터 기능을 구현합니다 | +| `skillshare-update-docs` | 모든 플래그를 소스와 교차 검증하며 최근 코드 변경 사항에 맞춰 웹사이트 문서를 업데이트합니다 | +| `skillshare-code-review` | 변경 사항을 병렬 패스(정확성, 저장소 규칙, 사양, 사용처, 정리)로 리뷰하고 각 지적을 검증합니다 | +| `skillshare-cli-e2e-test` | Runbook을 기반으로 devcontainer에서 격리된 E2E 테스트를 실행합니다 | +| `skillshare-changelog` | 최근 커밋으로부터 conventional 형식의 CHANGELOG.md 항목을 생성합니다 | ## 일반적인 워크플로 -1. **기능 시작** — agent에게 spec과 함께 `implement-feature`를 사용하도록 요청하세요 -2. **문서 업데이트** — 코드 변경 후 `update-docs`를 호출해 웹사이트 문서를 동기화하세요 -3. **일관성 감사** — `codebase-audit`를 실행해 플래그/문서 불일치를 잡아내세요 -4. **E2E 테스트 실행** — `cli-e2e-test`를 사용해 샌드박스에서 검증하세요 -5. **Changelog 작성** — 릴리스 전에 `changelog`를 호출하세요 +1. **기능 시작** — agent에게 spec과 함께 `skillshare-implement-feature`를 사용하도록 요청하세요 +2. **문서 업데이트** — 코드 변경 후 `skillshare-update-docs`를 호출해 웹사이트 문서를 동기화하세요 +3. **변경 사항 리뷰** — 커밋하거나 PR을 열기 전에 `skillshare-code-review`를 실행하세요 +4. **E2E 테스트 실행** — `skillshare-cli-e2e-test`를 사용해 샌드박스에서 검증하세요 +5. **Changelog 작성** — 릴리스 전에 `skillshare-changelog`를 호출하세요 ## 다음 단계는? diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md index 7a71de614..24cc087b0 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md @@ -25,19 +25,19 @@ skillshare sync -p | Skill | 作用 | |-------|-------------| -| `implement-feature` | 使用 TDD 工作流,根据 spec 文件或描述实现功能 | -| `update-docs` | 更新网站文档以匹配最近的代码变更,并将每个 flag 与源码交叉验证 | -| `codebase-audit` | 交叉验证 CLI flags、文档、测试与 targets,检查整个代码库的一致性 | -| `cli-e2e-test` | 依据 runbooks,在 devcontainer 中运行隔离的 E2E 测试 | -| `changelog` | 以约定式格式,根据最近的提交生成 CHANGELOG.md 条目 | +| `skillshare-implement-feature` | 使用 TDD 工作流,根据 spec 文件或描述实现功能 | +| `skillshare-update-docs` | 更新网站文档以匹配最近的代码变更,并将每个 flag 与源码交叉验证 | +| `skillshare-code-review` | 以并行检查(正确性、仓库规则、规格、使用处、清理)审查变更,并逐条验证发现的问题 | +| `skillshare-cli-e2e-test` | 依据 runbooks,在 devcontainer 中运行隔离的 E2E 测试 | +| `skillshare-changelog` | 以约定式格式,根据最近的提交生成 CHANGELOG.md 条目 | ## 典型工作流 -1. **开始一个功能** — 让你的 agent 使用 `implement-feature` 搭配一份 spec -2. **更新文档** — 代码变更后,调用 `update-docs` 来同步网站文档 -3. **审计一致性** — 运行 `codebase-audit` 以捕捉 flag 与文档不一致的地方 -4. **运行 E2E 测试** — 使用 `cli-e2e-test` 在沙盒中进行验证 -5. **撰写 changelog** — 发布前调用 `changelog` +1. **开始一个功能** — 让你的 agent 使用 `skillshare-implement-feature` 搭配一份 spec +2. **更新文档** — 代码变更后,调用 `skillshare-update-docs` 来同步网站文档 +3. **审查变更** — 提交或开 PR 前运行 `skillshare-code-review` +4. **运行 E2E 测试** — 使用 `skillshare-cli-e2e-test` 在沙盒中进行验证 +5. **撰写 changelog** — 发布前调用 `skillshare-changelog` ## 接下来? diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md index f7d67bfaa..d7f951a76 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md @@ -25,19 +25,19 @@ skillshare sync -p | Skill | 功能 | |-------|-------------| -| `implement-feature` | 使用 TDD 工作流程,根據 spec 檔案或描述實作功能 | -| `update-docs` | 更新網站文件以符合最新的程式碼變更,並交叉驗證每個 flag 是否與原始碼一致 | -| `codebase-audit` | 交叉驗證 CLI flags、文件、測試與 targets 在整個程式碼庫中的一致性 | -| `cli-e2e-test` | 根據 runbook 在 devcontainer 中執行隔離的 E2E 測試 | -| `changelog` | 以 conventional commit 格式,根據最近的 commits 產生 CHANGELOG.md 項目 | +| `skillshare-implement-feature` | 使用 TDD 工作流程,根據 spec 檔案或描述實作功能 | +| `skillshare-update-docs` | 更新網站文件以符合最新的程式碼變更,並交叉驗證每個 flag 是否與原始碼一致 | +| `skillshare-code-review` | 以平行檢查(正確性、儲存庫規則、規格、使用處、清理)審查變更,並逐條驗證發現的問題 | +| `skillshare-cli-e2e-test` | 根據 runbook 在 devcontainer 中執行隔離的 E2E 測試 | +| `skillshare-changelog` | 以 conventional commit 格式,根據最近的 commits 產生 CHANGELOG.md 項目 | ## 典型工作流程 -1. **開始一項功能** — 請你的 agent 搭配 spec 使用 `implement-feature` -2. **更新文件** — 程式碼變更後,呼叫 `update-docs` 以同步網站文件 -3. **稽核一致性** — 執行 `codebase-audit` 以抓出 flag 與文件不一致之處 -4. **執行 E2E 測試** — 使用 `cli-e2e-test` 在 sandbox 中驗證 -5. **撰寫 changelog** — 發布前呼叫 `changelog` +1. **開始一項功能** — 請你的 agent 搭配 spec 使用 `skillshare-implement-feature` +2. **更新文件** — 程式碼變更後,呼叫 `skillshare-update-docs` 以同步網站文件 +3. **審查變更** — 提交或開 PR 前執行 `skillshare-code-review` +4. **執行 E2E 測試** — 使用 `skillshare-cli-e2e-test` 在 sandbox 中驗證 +5. **撰寫 changelog** — 發布前呼叫 `skillshare-changelog` ## 接下來呢?