mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
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:
+5
-1
@@ -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/
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
.skillshare/skills/*
|
||||
@@ -0,0 +1,3 @@
|
||||
# BEGIN SKILLSHARE MANAGED - DO NOT EDIT
|
||||
logs/
|
||||
# END SKILLSHARE MANAGED
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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"
|
||||
'
|
||||
```
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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`
|
||||
Reference in New Issue
Block a user