mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 12:23:22 +00:00
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.
This commit is contained in:
@@ -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/<cmd>.go`:
|
|
||||||
- Check if `tests/integration/<cmd>_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/<cmd>.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.
|
|
||||||
@@ -25,19 +25,19 @@ Your AI agent now has access to specialized skills for working on this codebase.
|
|||||||
|
|
||||||
| Skill | What it does |
|
| Skill | What it does |
|
||||||
|-------|-------------|
|
|-------|-------------|
|
||||||
| `implement-feature` | Implement a feature from a spec file or description using TDD workflow |
|
| `skillshare-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 |
|
| `skillshare-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 |
|
| `skillshare-code-review` | Review a change in parallel passes (correctness, repo rules, spec, consumers, cleanup) and verify each finding |
|
||||||
| `cli-e2e-test` | Run isolated E2E tests in devcontainer from runbooks |
|
| `skillshare-cli-e2e-test` | Run isolated E2E tests in devcontainer from runbooks |
|
||||||
| `changelog` | Generate a CHANGELOG.md entry from recent commits in conventional format |
|
| `skillshare-changelog` | Generate a CHANGELOG.md entry from recent commits in conventional format |
|
||||||
|
|
||||||
## Typical Workflow
|
## Typical Workflow
|
||||||
|
|
||||||
1. **Start a feature** — ask your agent to use `implement-feature` with a spec
|
1. **Start a feature** — ask your agent to use `skillshare-implement-feature` with a spec
|
||||||
2. **Update docs** — after code changes, invoke `update-docs` to sync website docs
|
2. **Update docs** — after code changes, invoke `skillshare-update-docs` to sync website docs
|
||||||
3. **Audit consistency** — run `codebase-audit` to catch flag/doc mismatches
|
3. **Review the change** — run `skillshare-code-review` before committing or opening a PR
|
||||||
4. **Run E2E tests** — use `cli-e2e-test` to verify in a sandbox
|
4. **Run E2E tests** — use `skillshare-cli-e2e-test` to verify in a sandbox
|
||||||
5. **Write changelog** — invoke `changelog` before release
|
5. **Write changelog** — invoke `skillshare-changelog` before release
|
||||||
|
|
||||||
## What's Next?
|
## What's Next?
|
||||||
|
|
||||||
|
|||||||
+10
-10
@@ -26,19 +26,19 @@ skillshare sync -p
|
|||||||
|
|
||||||
| Skill | 何をするか |
|
| Skill | 何をするか |
|
||||||
|-------|-------------|
|
|-------|-------------|
|
||||||
| `implement-feature` | TDD ワークフローを使い、spec ファイルまたは説明から機能を実装する |
|
| `skillshare-implement-feature` | TDD ワークフローを使い、spec ファイルまたは説明から機能を実装する |
|
||||||
| `update-docs` | すべてのフラグを Source と照合しながら、Web サイトのドキュメントを最近のコード変更に合わせて更新する |
|
| `skillshare-update-docs` | すべてのフラグを Source と照合しながら、Web サイトのドキュメントを最近のコード変更に合わせて更新する |
|
||||||
| `codebase-audit` | CLI フラグ、ドキュメント、テスト、Target をコードベース全体で相互検証する |
|
| `skillshare-code-review` | 変更を並列パス(正確性、リポジトリのルール、仕様、利用箇所、クリーンアップ)でレビューし、各指摘を検証する |
|
||||||
| `cli-e2e-test` | runbook から devcontainer 内で隔離された E2E テストを実行する |
|
| `skillshare-cli-e2e-test` | runbook から devcontainer 内で隔離された E2E テストを実行する |
|
||||||
| `changelog` | 最近のコミットから conventional な形式で CHANGELOG.md のエントリを生成する |
|
| `skillshare-changelog` | 最近のコミットから conventional な形式で CHANGELOG.md のエントリを生成する |
|
||||||
|
|
||||||
## 典型的なワークフロー
|
## 典型的なワークフロー
|
||||||
|
|
||||||
1. **機能を始める** — Agent に spec を使って `implement-feature` を使うよう依頼する
|
1. **機能を始める** — Agent に spec を使って `skillshare-implement-feature` を使うよう依頼する
|
||||||
2. **ドキュメントを更新する** — コード変更後、`update-docs` を呼び出して Web サイトのドキュメントを Sync する
|
2. **ドキュメントを更新する** — コード変更後、`skillshare-update-docs` を呼び出して Web サイトのドキュメントを Sync する
|
||||||
3. **一貫性を監査する** — フラグ/ドキュメントの不一致を捕捉するために `codebase-audit` を実行する
|
3. **変更をレビューする** — コミットや PR の前に `skillshare-code-review` を実行する
|
||||||
4. **E2E テストを実行する** — サンドボックスで検証するために `cli-e2e-test` を使う
|
4. **E2E テストを実行する** — サンドボックスで検証するために `skillshare-cli-e2e-test` を使う
|
||||||
5. **changelog を書く** — リリース前に `changelog` を呼び出す
|
5. **changelog を書く** — リリース前に `skillshare-changelog` を呼び出す
|
||||||
|
|
||||||
## 次のステップ
|
## 次のステップ
|
||||||
|
|
||||||
|
|||||||
+10
-10
@@ -24,19 +24,19 @@ skillshare sync -p
|
|||||||
|
|
||||||
| Skill | 하는 일 |
|
| Skill | 하는 일 |
|
||||||
|-------|-------------|
|
|-------|-------------|
|
||||||
| `implement-feature` | TDD 워크플로를 사용해 spec 파일이나 설명으로부터 기능을 구현합니다 |
|
| `skillshare-implement-feature` | TDD 워크플로를 사용해 spec 파일이나 설명으로부터 기능을 구현합니다 |
|
||||||
| `update-docs` | 모든 플래그를 소스와 교차 검증하며 최근 코드 변경 사항에 맞춰 웹사이트 문서를 업데이트합니다 |
|
| `skillshare-update-docs` | 모든 플래그를 소스와 교차 검증하며 최근 코드 변경 사항에 맞춰 웹사이트 문서를 업데이트합니다 |
|
||||||
| `codebase-audit` | 코드베이스 전반에서 CLI 플래그, 문서, 테스트, Target의 일관성을 교차 검증합니다 |
|
| `skillshare-code-review` | 변경 사항을 병렬 패스(정확성, 저장소 규칙, 사양, 사용처, 정리)로 리뷰하고 각 지적을 검증합니다 |
|
||||||
| `cli-e2e-test` | Runbook을 기반으로 devcontainer에서 격리된 E2E 테스트를 실행합니다 |
|
| `skillshare-cli-e2e-test` | Runbook을 기반으로 devcontainer에서 격리된 E2E 테스트를 실행합니다 |
|
||||||
| `changelog` | 최근 커밋으로부터 conventional 형식의 CHANGELOG.md 항목을 생성합니다 |
|
| `skillshare-changelog` | 최근 커밋으로부터 conventional 형식의 CHANGELOG.md 항목을 생성합니다 |
|
||||||
|
|
||||||
## 일반적인 워크플로
|
## 일반적인 워크플로
|
||||||
|
|
||||||
1. **기능 시작** — agent에게 spec과 함께 `implement-feature`를 사용하도록 요청하세요
|
1. **기능 시작** — agent에게 spec과 함께 `skillshare-implement-feature`를 사용하도록 요청하세요
|
||||||
2. **문서 업데이트** — 코드 변경 후 `update-docs`를 호출해 웹사이트 문서를 동기화하세요
|
2. **문서 업데이트** — 코드 변경 후 `skillshare-update-docs`를 호출해 웹사이트 문서를 동기화하세요
|
||||||
3. **일관성 감사** — `codebase-audit`를 실행해 플래그/문서 불일치를 잡아내세요
|
3. **변경 사항 리뷰** — 커밋하거나 PR을 열기 전에 `skillshare-code-review`를 실행하세요
|
||||||
4. **E2E 테스트 실행** — `cli-e2e-test`를 사용해 샌드박스에서 검증하세요
|
4. **E2E 테스트 실행** — `skillshare-cli-e2e-test`를 사용해 샌드박스에서 검증하세요
|
||||||
5. **Changelog 작성** — 릴리스 전에 `changelog`를 호출하세요
|
5. **Changelog 작성** — 릴리스 전에 `skillshare-changelog`를 호출하세요
|
||||||
|
|
||||||
## 다음 단계는?
|
## 다음 단계는?
|
||||||
|
|
||||||
|
|||||||
+10
-10
@@ -25,19 +25,19 @@ skillshare sync -p
|
|||||||
|
|
||||||
| Skill | 作用 |
|
| Skill | 作用 |
|
||||||
|-------|-------------|
|
|-------|-------------|
|
||||||
| `implement-feature` | 使用 TDD 工作流,根据 spec 文件或描述实现功能 |
|
| `skillshare-implement-feature` | 使用 TDD 工作流,根据 spec 文件或描述实现功能 |
|
||||||
| `update-docs` | 更新网站文档以匹配最近的代码变更,并将每个 flag 与源码交叉验证 |
|
| `skillshare-update-docs` | 更新网站文档以匹配最近的代码变更,并将每个 flag 与源码交叉验证 |
|
||||||
| `codebase-audit` | 交叉验证 CLI flags、文档、测试与 targets,检查整个代码库的一致性 |
|
| `skillshare-code-review` | 以并行检查(正确性、仓库规则、规格、使用处、清理)审查变更,并逐条验证发现的问题 |
|
||||||
| `cli-e2e-test` | 依据 runbooks,在 devcontainer 中运行隔离的 E2E 测试 |
|
| `skillshare-cli-e2e-test` | 依据 runbooks,在 devcontainer 中运行隔离的 E2E 测试 |
|
||||||
| `changelog` | 以约定式格式,根据最近的提交生成 CHANGELOG.md 条目 |
|
| `skillshare-changelog` | 以约定式格式,根据最近的提交生成 CHANGELOG.md 条目 |
|
||||||
|
|
||||||
## 典型工作流
|
## 典型工作流
|
||||||
|
|
||||||
1. **开始一个功能** — 让你的 agent 使用 `implement-feature` 搭配一份 spec
|
1. **开始一个功能** — 让你的 agent 使用 `skillshare-implement-feature` 搭配一份 spec
|
||||||
2. **更新文档** — 代码变更后,调用 `update-docs` 来同步网站文档
|
2. **更新文档** — 代码变更后,调用 `skillshare-update-docs` 来同步网站文档
|
||||||
3. **审计一致性** — 运行 `codebase-audit` 以捕捉 flag 与文档不一致的地方
|
3. **审查变更** — 提交或开 PR 前运行 `skillshare-code-review`
|
||||||
4. **运行 E2E 测试** — 使用 `cli-e2e-test` 在沙盒中进行验证
|
4. **运行 E2E 测试** — 使用 `skillshare-cli-e2e-test` 在沙盒中进行验证
|
||||||
5. **撰写 changelog** — 发布前调用 `changelog`
|
5. **撰写 changelog** — 发布前调用 `skillshare-changelog`
|
||||||
|
|
||||||
## 接下来?
|
## 接下来?
|
||||||
|
|
||||||
|
|||||||
+10
-10
@@ -25,19 +25,19 @@ skillshare sync -p
|
|||||||
|
|
||||||
| Skill | 功能 |
|
| Skill | 功能 |
|
||||||
|-------|-------------|
|
|-------|-------------|
|
||||||
| `implement-feature` | 使用 TDD 工作流程,根據 spec 檔案或描述實作功能 |
|
| `skillshare-implement-feature` | 使用 TDD 工作流程,根據 spec 檔案或描述實作功能 |
|
||||||
| `update-docs` | 更新網站文件以符合最新的程式碼變更,並交叉驗證每個 flag 是否與原始碼一致 |
|
| `skillshare-update-docs` | 更新網站文件以符合最新的程式碼變更,並交叉驗證每個 flag 是否與原始碼一致 |
|
||||||
| `codebase-audit` | 交叉驗證 CLI flags、文件、測試與 targets 在整個程式碼庫中的一致性 |
|
| `skillshare-code-review` | 以平行檢查(正確性、儲存庫規則、規格、使用處、清理)審查變更,並逐條驗證發現的問題 |
|
||||||
| `cli-e2e-test` | 根據 runbook 在 devcontainer 中執行隔離的 E2E 測試 |
|
| `skillshare-cli-e2e-test` | 根據 runbook 在 devcontainer 中執行隔離的 E2E 測試 |
|
||||||
| `changelog` | 以 conventional commit 格式,根據最近的 commits 產生 CHANGELOG.md 項目 |
|
| `skillshare-changelog` | 以 conventional commit 格式,根據最近的 commits 產生 CHANGELOG.md 項目 |
|
||||||
|
|
||||||
## 典型工作流程
|
## 典型工作流程
|
||||||
|
|
||||||
1. **開始一項功能** — 請你的 agent 搭配 spec 使用 `implement-feature`
|
1. **開始一項功能** — 請你的 agent 搭配 spec 使用 `skillshare-implement-feature`
|
||||||
2. **更新文件** — 程式碼變更後,呼叫 `update-docs` 以同步網站文件
|
2. **更新文件** — 程式碼變更後,呼叫 `skillshare-update-docs` 以同步網站文件
|
||||||
3. **稽核一致性** — 執行 `codebase-audit` 以抓出 flag 與文件不一致之處
|
3. **審查變更** — 提交或開 PR 前執行 `skillshare-code-review`
|
||||||
4. **執行 E2E 測試** — 使用 `cli-e2e-test` 在 sandbox 中驗證
|
4. **執行 E2E 測試** — 使用 `skillshare-cli-e2e-test` 在 sandbox 中驗證
|
||||||
5. **撰寫 changelog** — 發布前呼叫 `changelog`
|
5. **撰寫 changelog** — 發布前呼叫 `skillshare-changelog`
|
||||||
|
|
||||||
## 接下來呢?
|
## 接下來呢?
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user