feat: migrate contributor skills to .skillshare/skills/ for project-mode sharing

Move 5 skills from .claude/commands/ to .skillshare/skills/ so contributors
can share them via `skillshare sync -p`. Each skill has clear responsibility:
- cli-e2e-test: run isolated E2E tests in devcontainer
- codebase-audit: read-only cross-validation of code/docs/tests
- implement-feature: TDD workflow with E2E runbook generation
- update-docs: sync website docs with code changes
- changelog: generate CHANGELOG entries (RELEASE_NOTES maintainer-only)

Also:
- .gitignore: allow .skillshare/skills/, config.yaml, .gitignore to be tracked
- .skillignore: block .skillshare/skills/* from external install discovery
- ai_docs/tests/README.md: content merged into cli-e2e-test skill
This commit is contained in:
Willie
2026-02-25 07:02:54 +08:00
parent 42c383dd83
commit 2ee8033171
10 changed files with 656 additions and 68 deletions
+5 -1
View File
@@ -20,7 +20,11 @@ coverage.out
AGENTS.md
CLAUDE.md
docs/plans/
.skillshare/
.agents/
.skillshare/*
!.skillshare/skills/
!.skillshare/config.yaml
!.skillshare/.gitignore
/specs/
.pnpm-store/
.feature-radar/
+1
View File
@@ -0,0 +1 @@
.skillshare/skills/*
+3
View File
@@ -0,0 +1,3 @@
# BEGIN SKILLSHARE MANAGED - DO NOT EDIT
logs/
# END SKILLSHARE MANAGED
+6
View File
@@ -0,0 +1,6 @@
# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/project-config.schema.json
targets:
- universal
- claude
audit:
block_threshold: CRITICAL
+108
View File
@@ -0,0 +1,108 @@
---
name: skillshare-changelog
description: Generate CHANGELOG.md entry from recent commits in conventional format
argument-hint: "[tag-version]"
targets: [claude, codex]
---
Generate a CHANGELOG.md entry for a release. $ARGUMENTS specifies the tag version (e.g., `v0.16.0`) or omit to auto-detect via `git describe --tags --abbrev=0`.
**Scope**: This skill only updates `CHANGELOG.md`. It does NOT write code (use `implement-feature`) or update docs (use `update-docs`).
## Workflow
### Step 1: Determine Version Range
```bash
# Auto-detect latest tag
LATEST_TAG=$(git describe --tags --abbrev=0)
# Find previous tag
PREV_TAG=$(git describe --tags --abbrev=0 "${LATEST_TAG}^")
echo "Generating changelog: $PREV_TAG → $LATEST_TAG"
```
### Step 2: Collect Commits
```bash
git log "${PREV_TAG}..${LATEST_TAG}" --oneline --no-merges
```
### Step 3: Categorize Changes
Group commits by conventional commit type:
| Prefix | Category |
|--------|----------|
| `feat` | New Features |
| `fix` | Bug Fixes |
| `refactor` | Refactoring |
| `docs` | Documentation |
| `perf` | Performance |
| `test` | Tests |
| `chore` | Maintenance |
### Step 4: Write User-Facing Entry
Write from the **user's perspective**. Only include changes users will notice or care about.
**Include**:
- New features with usage examples (CLI commands)
- Bug fixes that affected user-visible behavior
- Breaking changes (renames, removed flags, scope changes)
- Performance improvements users would notice
**Exclude**:
- Internal test changes (smoke tests, test refactoring)
- Implementation details (error propagation, internal structs)
- Dev toolchain changes (Makefile cleanup, CI tweaks)
- Pure documentation adjustments
**Wording guidelines**:
- Don't use "first-class", "recommended" for non-default options
- Be factual: "Added X" / "Fixed Y" / "Renamed A to B"
- Include CLI example when introducing a new feature
### Step 5: Update CHANGELOG.md
Read existing `CHANGELOG.md` and insert new entry at the top, after the header.
Format:
```markdown
## [vX.Y.Z] - YYYY-MM-DD
### New Features
- **Feature name**: Brief description (`skillshare command --flag`)
### Bug Fixes
- Fixed issue where X happened when Y
### Breaking Changes
- Renamed `old-name` to `new-name`
```
### Step 6: RELEASE_NOTES (Maintainer Only)
**IMPORTANT**: `specs/RELEASE_NOTES_<version>.md` is only generated when the user is the project maintainer (runkids). Contributors should skip this step.
Check if running as maintainer:
```bash
git config user.name # Should match maintainer identity
```
If maintainer:
- Generate `specs/RELEASE_NOTES_${LATEST_TAG}.md` with detailed release notes
- Include migration guide if breaking changes exist
If not maintainer:
- Skip RELEASE_NOTES generation
- Only update CHANGELOG.md
## Rules
- **User perspective** — write for users, not developers
- **No fabricated links** — never invent URLs or references
- **Verify features exist** — grep source before claiming a feature was added
- **No internal noise** — exclude test-only, CI-only, or refactor-only changes
- **Conventional format** — follow existing CHANGELOG.md style exactly
- **RELEASE_NOTES = maintainer only** — contributors only update CHANGELOG.md
+157
View File
@@ -0,0 +1,157 @@
---
name: skillshare-cli-e2e-test
description: Run isolated E2E tests in devcontainer from ai_docs/tests runbooks
argument-hint: "[runbook-name | new]"
targets: [claude, codex]
---
Run isolated E2E tests in devcontainer. $ARGUMENTS specifies runbook name or "new".
## Flow
### Phase 0: Environment Check
1. Confirm devcontainer is running:
```bash
docker compose -f .devcontainer/docker-compose.yml ps --format json
```
- If not running → prompt user: `docker compose -f .devcontainer/docker-compose.yml up -d`
- Wait until container is running
2. Confirm Linux binary is available:
```bash
docker exec skillshare_devcontainer-skillshare-devcontainer-1 bash -c \
'/workspace/.devcontainer/ensure-skillshare-linux-binary.sh && ss version'
```
### Phase 1: Detect Scope
1. Read all `*_runbook.md` files under `ai_docs/tests/` to list available runbooks
2. Read `git diff HEAD~3 --stat` to identify recent code changes
3. Match changes to relevant runbooks (compare runbook Scope sections with changed file paths)
### Phase 2: Select Tests
Prompt user (via AskUserQuestion):
- **Option A**: Run existing runbook (list all available + mark those related to recent changes)
- **Option B**: Auto-generate new test script based on recent changes
- **Option C**: If $ARGUMENTS specifies a runbook, skip to Phase 3
### Phase 3: Prepare & Execute
#### Running existing runbook:
1. Read the selected runbook `.md` file
2. Create isolated environment and execute step by step:
```bash
# Container name
CONTAINER="skillshare_devcontainer-skillshare-devcontainer-1"
ENV_NAME="e2e-$(date +%Y%m%d-%H%M%S)"
# Create isolated environment
docker exec $CONTAINER ssenv create "$ENV_NAME"
# Isolated HOME has no target dirs by default — create them before init
docker exec $CONTAINER ssenv enter "$ENV_NAME" -- mkdir -p ~/.claude ~/.codex
# Execute each step from runbook (ssenv enter isolates HOME)
docker exec $CONTAINER ssenv enter "$ENV_NAME" -- <command>
```
3. After each step, verify conditions in the Expected block
4. Mark each step PASS / FAIL
#### Generating new script:
1. Read `git diff HEAD~3` to find changed files in `cmd/skillshare/` or `internal/`
2. Read changed files to understand new/modified functionality
3. Generate new runbook to `ai_docs/tests/<slug>_runbook.md`, following existing conventions:
- YAML-free, pure Markdown
- Has Scope, Environment, Steps (each with bash + Expected), Pass Criteria
4. Then execute the new runbook (same flow as above)
### Phase 4: Cleanup & Report
1. Clean up isolated environment:
```bash
docker exec $CONTAINER ssenv delete "$ENV_NAME" --force
```
2. Output summary:
```
── E2E Test Report ──
Runbook: {runbook name}
Env: {ENV_NAME}
Duration: {time}
Step 1: {description} PASS
Step 2: {description} PASS
Step 3: {description} FAIL ← {error detail}
...
Result: {N}/{total} passed
```
3. If any FAIL → analyze cause, provide fix suggestions
## Rules
- **Always execute inside devcontainer** — use `docker exec`, never run CLI on host
- **Always use `ssenv` for HOME isolation** — don't pollute container default HOME
- **Verify every step** — never skip Expected checks
- **Don't abort on failure** — record FAIL, continue to next step, summarize at end
- **Always clean up** — Phase 4 must delete the ssenv environment
- **`ss` = `skillshare`** — same binary in runbooks
- **`~` = ssenv-isolated HOME** — `ssenv enter` auto-sets `HOME`
- **Create target dirs first** — isolated HOME has no `.claude`/`.codex` etc.; `mkdir -p` before `init`
## ssenv Quick Reference
| Command | Purpose |
|---------|---------|
| `sshelp` | Show shortcuts and usage |
| `ssls` | List isolated environments |
| `ssnew <name>` | Create + enter isolated shell (interactive) |
| `ssuse <name>` | Enter existing isolated shell (interactive) |
| `ssback` | Leave isolated context |
| `ssenv enter <name> -- <cmd>` | Run single command in isolation (automation) |
- For interactive debugging: `ssnew <env>` then `exit` when done
- For deterministic automation: prefer `ssenv enter <env> -- <command>` one-liners
## Test Command Policy
When running Go tests inside devcontainer (not via runbook):
```bash
go build -o bin/skillshare ./cmd/skillshare
SKILLSHARE_TEST_BINARY="$PWD/bin/skillshare" go test ./tests/integration -count=1
go test ./...
```
Always run in devcontainer unless there is a documented exception.
## Container Command Templates
```bash
# Single command
docker exec $CONTAINER ssenv enter "$ENV_NAME" -- ss status
# Multi-line compound command (use bash -c)
docker exec $CONTAINER ssenv enter "$ENV_NAME" -- bash -c '
ss init --no-copy --all-targets --no-git --no-skill
ss status
'
# Check files (HOME is set to isolated path by ssenv)
docker exec $CONTAINER ssenv enter "$ENV_NAME" -- bash -c '
cat ~/.config/skillshare/config.yaml
'
# With environment variables
docker exec $CONTAINER ssenv enter "$ENV_NAME" -- bash -c '
TARGET=~/.claude/skills
ls -la "$TARGET"
'
```
+110
View File
@@ -0,0 +1,110 @@
---
name: skillshare-codebase-audit
description: Cross-validate CLI flags, docs, tests, and targets for consistency across the codebase
targets: [claude, codex]
---
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.
## Audit Dimensions
Run all 4 dimensions 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/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. Spec vs Code
For each spec in `specs/` marked as completed/done:
- Verify the described feature exists in source code
- Check that the spec's acceptance criteria are testable
Report:
- **IMPLEMENTED**: Spec complete, code exists
- **MISMATCH**: Spec says done but code missing or partial
- **PENDING**: Spec not yet marked complete (informational)
### 3. 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
### 4. Target Audit
Verify `internal/config/targets.yaml` entries:
- Each target has both `global_path` and `project_path`
- Aliases are consistent
- No duplicate entries
Report:
- **OK**: Target entry complete and valid
- **INCOMPLETE**: Missing required fields
- **DUPLICATE**: Name or alias collision
## Output Format
```
== Skillshare Codebase Audit ==
### CLI Flags (N issues)
| Command | Flag | Status |
|-----------|-------------|--------------|
| install | --force | OK |
| install | --into | UNDOCUMENTED |
### Specs (N issues)
| Spec File | Status |
|----------------------|-------------|
| copy-sync-mode.md | IMPLEMENTED |
| some-feature.md | MISMATCH |
### 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 project_path |
== Summary: X OK / Y issues found ==
```
## Rules
- **Read-only** — never modify files, only report
- **Evidence-based** — every finding must include file path and line number
- **No false positives** — verify with grep before flagging
- **Scope $ARGUMENTS** — if user specifies "flags", only run dimension 1
@@ -0,0 +1,166 @@
---
name: skillshare-implement-feature
description: Implement a feature from a spec file or description using TDD workflow
argument-hint: "[spec-file-path | feature description]"
targets: [claude, codex]
---
Implement a feature following TDD workflow. $ARGUMENTS is a spec file path (e.g., `specs/my-feature.md`) or a plain-text feature description.
**Scope**: This skill writes Go code and tests. It does NOT update website docs (use `update-docs` after) or CHANGELOG (use `changelog` after).
## Workflow
### Step 1: Understand Requirements
If $ARGUMENTS is a file path:
1. Read the spec file
2. Extract acceptance criteria and edge cases
3. Identify affected packages
If $ARGUMENTS is a description:
1. Search existing code for related functionality
2. Identify the right package to extend
3. Confirm scope with user before proceeding
### Step 2: Identify Affected Files
List all files that will be created or modified:
```bash
# Typical pattern for a new command
cmd/skillshare/<command>.go # Command handler
cmd/skillshare/<command>_project.go # Project-mode handler (if dual-mode)
internal/<package>/<feature>.go # Core logic
tests/integration/<command>_test.go # Integration test
```
Display the file list and continue. If scope is unclear, ask the user.
### Step 3: Write Failing Tests First (RED)
Write integration tests using `testutil.Sandbox`:
```go
func TestFeature_BasicCase(t *testing.T) {
sb := testutil.NewSandbox(t)
defer sb.Cleanup()
// Setup
sb.CreateSkill("test-skill", map[string]string{
"SKILL.md": "---\nname: test-skill\n---\n# Content",
})
// Act
result := sb.RunCLI("command", "args...")
// Assert
result.AssertSuccess()
result.AssertOutputContains("expected output")
}
```
Verify tests fail:
```bash
make test-int
# or run specific test:
go test ./tests/integration -run TestFeature_BasicCase
```
### Step 4: Implement (GREEN)
Write minimal code to make tests pass:
1. Follow existing patterns in `cmd/skillshare/` and `internal/`
2. Use `internal/ui` for terminal output (colors, spinners, boxes)
3. Add oplog instrumentation for mutating commands:
```go
start := time.Now()
// ... do work ...
e := oplog.NewEntry("command-name", statusFromErr(err), time.Since(start))
oplog.Write(configPath, oplog.OpsFile, e)
```
4. Register command in `main.go` commands map if new command
Verify tests pass:
```bash
make test-int
```
### Step 5: Refactor and Verify
1. Clean up code while keeping tests green
2. Run full quality check:
```bash
make check # fmt-check + lint + test
```
3. Fix any formatting or lint issues
### Step 6: E2E Runbook (Major Features Only)
If the feature meets **any** of these criteria, generate an E2E runbook:
- New command or subcommand
- Changes to install/uninstall/sync flow
- Security-related (audit, hash verification, rollback)
- Multi-step user workflow (init → install → sync → verify)
- Edge cases that integration tests alone can't cover (Docker, network, file permissions)
Generate `ai_docs/tests/<slug>_runbook.md` following the existing convention:
```markdown
# CLI E2E Runbook: <Title>
<One-line summary of what this validates.>
**Origin**: <version> — <why this runbook exists>
## Scope
- <bullet list of behaviors being validated>
## Environment
Run inside devcontainer with `ssenv` isolation.
## Steps
### 1. Setup: <description>
\```bash
<commands>
\```
**Expected**: <what should happen>
### 2. <Action>: <description>
...
## Pass Criteria
- All steps marked PASS
- <additional criteria>
```
Key conventions:
- YAML-free, pure Markdown
- Each step has `bash` block + `Expected` block
- `ss` = `skillshare`, `~` = ssenv-isolated HOME
- Runbook can be executed by the `cli-e2e-test` skill
If the feature does not meet the criteria above, skip this step.
### Step 7: Stage and Report
1. List all created/modified files
2. Confirm each acceptance criterion is met with test evidence
3. Remind user to run `update-docs` if the feature affects CLI flags or user-visible behavior
## Rules
- **Test-first** — always write failing test before implementation
- **Minimal code** — only write what's needed to pass tests
- **Follow patterns** — match existing code style in each package
- **3-strike rule** — if a test fails 3 times after fixes, stop and report what's blocking
- **No docs** — this skill writes code only; use `update-docs` for documentation
- **No changelog** — use `changelog` skill for release notes
- **Spec ambiguity** — ask the user rather than guessing
+100
View File
@@ -0,0 +1,100 @@
---
name: skillshare-update-docs
description: Update website docs to match recent code changes, cross-validating every flag against source
argument-hint: "[command-name | commit-range]"
targets: [claude, codex]
---
Sync website documentation with recent code changes. $ARGUMENTS specifies scope: a command name (e.g., `install`), commit range, or omit to auto-detect from `git diff HEAD~1`.
**Scope**: This skill only updates `website/docs/`. It does NOT write Go code (use `implement-feature`) or CHANGELOG (use `changelog`).
## Workflow
### Step 1: Detect Changes
```bash
# Auto-detect recently changed commands
git diff HEAD~1 --stat -- cmd/skillshare/ internal/
```
Map changed files to affected documentation:
- `cmd/skillshare/install.go` → `website/docs/commands/install.md`
- `internal/audit/` → `website/docs/commands/audit.md`
- `internal/config/targets.yaml` → `website/docs/reference/supported-targets.md`
### Step 2: Cross-Validate Flags
For each affected command:
1. Read the Go source to extract actual flags and behavior:
```bash
grep -n 'flag\.\|Usage\|Args' cmd/skillshare/<cmd>.go
```
2. Read the corresponding doc page:
```
website/docs/commands/<cmd>.md
```
3. Compare and fix:
- **New flags** in code → add to docs with usage example
- **Removed flags** from code → remove from docs
- **Changed behavior** → update description
- **Every `--flag` in docs** must have a matching `grep` hit in source
### Step 3: Update Documentation
Apply changes following existing doc conventions:
- Match heading structure of neighboring doc pages
- Include CLI examples with expected output
- Keep flag tables consistent in format
### Step 4: Check Built-in Skill
If changes affect user-visible CLI behavior:
1. Read `skills/skillshare/SKILL.md`
2. Check if the built-in skill description needs updating
3. Verify description stays under 1024 characters (CodeX limit)
### Step 5: Check README
Review `README.md` for sections that may need updates:
- Recent Updates section
- Feature list
- Usage examples
### Step 6: Build Verification
```bash
cd website && npm run build
```
Confirm no broken links or build errors.
### Step 7: Report
List all changes made with rationale:
```
== Documentation Updates ==
Modified:
website/docs/commands/install.md
- Added --into flag documentation
- Updated install examples
skills/skillshare/SKILL.md
- Added --into to feature list (desc: 987/1024 chars)
Build: PASS (no broken links)
```
## Rules
- **Source of truth is code** — docs must match what the code actually does
- **Every flag claim must be verified** — grep source before writing docs
- **No speculative docs** — never document planned but unimplemented features
- **No code changes** — this skill only touches `website/docs/`, `skills/skillshare/SKILL.md`, and `README.md`
- **Preserve style** — match existing doc page structure and tone
- **Built-in skill desc limit** — must stay under 1024 characters
-67
View File
@@ -1,67 +0,0 @@
# AI Testing Guide (Devcontainer + ssenv)
This guide is for AI agents running tests/verification in this repository.
## Non-negotiable rules
1. Always run tests inside devcontainer.
2. Always use an isolated `ssenv` environment for runtime verification.
3. Never rely on host `HOME` for CLI behavior checks.
4. End each run with explicit cleanup (`ssenv delete <name> --force`).
## Required bootstrap
From repository root:
```bash
docker compose -f .devcontainer/docker-compose.yml up -d
docker exec -it skillshare_devcontainer-skillshare-devcontainer-1 bash
```
Inside container:
```bash
/workspace/.devcontainer/ensure-skillshare-linux-binary.sh
sshelp
```
## Standard AI workflow
Use this pattern for every verification run:
```bash
ENV_NAME="ai-test-$(date +%Y%m%d-%H%M%S)"
ssenv create "$ENV_NAME"
ssenv enter "$ENV_NAME" -- ss init --no-copy --no-targets --no-git --no-skill
ssenv enter "$ENV_NAME" -- ss doctor
ssenv delete "$ENV_NAME" --force
```
Notes:
- For interactive debugging, use `ssuse <env>` or `ssnew <env>`, then `exit` when done.
- For deterministic automation, prefer `ssenv enter <env> -- <command>` one-liners.
- If `ssenv delete <active-env> --force` is called from an eval-switched shell, it auto-returns to `/workspace`.
## Test command policy
Run in devcontainer unless there is a documented exception.
```bash
go build -o bin/skillshare ./cmd/skillshare
SKILLSHARE_TEST_BINARY="$PWD/bin/skillshare" go test ./tests/integration -count=1
go test ./...
```
## Quick commands reference
- `sshelp`: show shortcuts and usage.
- `ssls`: list isolated environments.
- `ssnew <name>`: create + enter isolated shell.
- `ssuse <name>`: enter existing isolated shell.
- `ssback`: leave isolated context helper.
- `ssenv shortcuts`: print the same shortcuts reference.
## Related runbook
- `ai_docs/tests/first_use_cli_e2e_runbook.md`