jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(skills): trim duplication and improve progressive disclosure

Browse Source 
- search-docs: remove content already in CLAUDE.md (basic commands,
  endpoints, examples), keep only unique operations and workflows
- ticket: remove duplicated access method and SQL wrapper docs, add
  missing show --brief command reference
- review-pr: extract branch-type reviewer profiles to
  references/reviewer-profiles.md, reducing SKILL.md from 287 to 187
  lines while preserving all reviewer specifications
- create-skill: remove empty .gitkeep placeholders from unused
  references/ and scripts/ directories

Reviewed all skills against /create-skill conventions. Main findings
were CLAUDE.md content duplication wasting context tokens and a
progressive disclosure opportunity in the longest skill.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-02-12 18:41:53 +01:00
co-authored by Claude Opus 4.6
parent 1761e1aa11
commit f1bc79a0d2
6 changed files with 121 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/create-skill/references/.gitkeep
View File
.claude/skills/create-skill/scripts/.gitkeep
View File
.claude/skills/review-pr/SKILL.md
+3 -103
View File
@@ -73,110 +73,10 @@ raw diff to reviewers — cleaner context, better reviews. Read files with
### 4. Spawn reviewers in parallel ### 4. Spawn reviewers in parallel
Use the Task tool to spawn **all reviewers simultaneously** in a single message. Use the Task tool to spawn **all reviewers simultaneously** in a single message.
Use `model: sonnet` for all — sufficient for review, saves cost.
--- Read `references/reviewer-profiles.md` for the full per-branch-type reviewer
specifications (agent types, models, prompt focus areas). Match the branch type
#### Code reviews (`server`, `client`, `ci`) from step 2 to the corresponding section.
**Hoshe (Code Quality)**
- `subagent_type`: `hoshe`, `model`: `sonnet`
- Prompt: Include source code and commit log. Ask Hoshe to review for:
- Correctness and bug risks
- Error handling gaps
- Test coverage (are new features tested?)
- Code style and clarity
- Security concerns (OWASP top 10, injection risks)
- Performance issues
**Tyre (Architecture)**
- `subagent_type`: `tyre`, `model`: `sonnet`
- Prompt: Include source code and commit log. Tell Tyre to read the relevant
`decisions/*.md` files first, then review for:
- Architectural consistency with project decisions
- API/interface design quality
- Dependency and coupling concerns
- Scalability implications
- Whether the change respects non-negotiable baselines (D-010, D-012)
- Tyre can read files directly from the branch using `git show origin/<branch>:<path>`
---
#### Copy reviews (`copy`)
**Hoshe (QA)**
- `subagent_type`: `hoshe`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Ask Hoshe to review for:
- Formatting consistency (markdown, file naming, frontmatter)
- Broken references or links
- Spelling and grammar
- File organization and structure
- Missing or orphaned files
**Paula (Narrative Depth)**
- `subagent_type`: `paula`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Tell Paula to read the
relevant `decisions/*.md` files first, then review for:
- Narrative quality and character voice consistency
- Whether dialogue and monologue feel authentic to the characters
- Consequences and stakes — do choices carry weight?
- Political and interpersonal depth
- Emotional resonance — does the text make you feel something?
**Miri (World Consistency)**
- `subagent_type`: `miri`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Tell Miri to read the
relevant `decisions/*.md` files first, then review for:
- Lore accuracy — do facts match established setting?
- Internal consistency across files
- IP originality — nothing should read as a copy from another franchise
- Faction, technology, and location details match the worldbuilding docs
- Setting serves gameplay mechanics (asymmetric information, perception)
---
#### Visual reviews (`visual`)
**Hoshe (QA)**
- `subagent_type`: `hoshe`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Ask Hoshe to review for:
- File format and naming conventions
- Asset organization and directory structure
- Missing or broken references in scene/resource files
- Import settings consistency
**Araminta (Art Direction)**
- `subagent_type`: `araminta`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Tell Araminta to read
the style guide and relevant design docs first, then review for:
- Visual consistency with the established style guide
- Color palette adherence
- UI pattern consistency (diegetic-first, clarity over beauty)
- Whether assets scale gracefully (boxes-with-labels to full-art)
- Mood and tone — sleek, advanced, subtle Commonwealth aesthetic
---
#### Audio reviews (`audio`)
**Hoshe (QA)**
- `subagent_type`: `hoshe`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Ask Hoshe to review for:
- File format and naming conventions
- Audio asset organization and directory structure
- Missing or broken references
- Import/bus configuration consistency
**Ozzie (Player Experience)**
- `subagent_type`: `ozzie`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Ask Ozzie to review for:
- Emotional impact — does the audio enhance the moment?
- Atmosphere and tone — does it feel like the Commonwealth?
- Player feedback clarity — can the player tell what just happened?
- Pacing — do sounds support or fight the gameplay rhythm?
- Memorable moments — will players remember these audio cues?
---
All reviewers: request structured verdict: APPROVE or REQUEST_CHANGES with All reviewers: request structured verdict: APPROVE or REQUEST_CHANGES with
file-specific comments. file-specific comments.
.claude/skills/review-pr/references/reviewer-profiles.md
+96
View File
@@ -0,0 +1,96 @@
# Reviewer Profiles by Branch Type
Use `model: sonnet` for all reviewers — sufficient for review, saves cost.
## Code reviews (`server`, `client`, `ci`)
**Hoshe (Code Quality)**
- `subagent_type`: `hoshe`, `model`: `sonnet`
- Prompt: Include source code and commit log. Ask Hoshe to review for:
- Correctness and bug risks
- Error handling gaps
- Test coverage (are new features tested?)
- Code style and clarity
- Security concerns (OWASP top 10, injection risks)
- Performance issues
**Tyre (Architecture)**
- `subagent_type`: `tyre`, `model`: `sonnet`
- Prompt: Include source code and commit log. Tell Tyre to read the relevant
`decisions/*.md` files first, then review for:
- Architectural consistency with project decisions
- API/interface design quality
- Dependency and coupling concerns
- Scalability implications
- Whether the change respects non-negotiable baselines (D-010, D-012)
- Tyre can read files directly from the branch using `git show origin/<branch>:<path>`
## Copy reviews (`copy`)
**Hoshe (QA)**
- `subagent_type`: `hoshe`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Ask Hoshe to review for:
- Formatting consistency (markdown, file naming, frontmatter)
- Broken references or links
- Spelling and grammar
- File organization and structure
- Missing or orphaned files
**Paula (Narrative Depth)**
- `subagent_type`: `paula`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Tell Paula to read the
relevant `decisions/*.md` files first, then review for:
- Narrative quality and character voice consistency
- Whether dialogue and monologue feel authentic to the characters
- Consequences and stakes — do choices carry weight?
- Political and interpersonal depth
- Emotional resonance — does the text make you feel something?
**Miri (World Consistency)**
- `subagent_type`: `miri`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Tell Miri to read the
relevant `decisions/*.md` files first, then review for:
- Lore accuracy — do facts match established setting?
- Internal consistency across files
- IP originality — nothing should read as a copy from another franchise
- Faction, technology, and location details match the worldbuilding docs
- Setting serves gameplay mechanics (asymmetric information, perception)
## Visual reviews (`visual`)
**Hoshe (QA)**
- `subagent_type`: `hoshe`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Ask Hoshe to review for:
- File format and naming conventions
- Asset organization and directory structure
- Missing or broken references in scene/resource files
- Import settings consistency
**Araminta (Art Direction)**
- `subagent_type`: `araminta`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Tell Araminta to read
the style guide and relevant design docs first, then review for:
- Visual consistency with the established style guide
- Color palette adherence
- UI pattern consistency (diegetic-first, clarity over beauty)
- Whether assets scale gracefully (boxes-with-labels to full-art)
- Mood and tone — sleek, advanced, subtle Commonwealth aesthetic
## Audio reviews (`audio`)
**Hoshe (QA)**
- `subagent_type`: `hoshe`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Ask Hoshe to review for:
- File format and naming conventions
- Audio asset organization and directory structure
- Missing or broken references
- Import/bus configuration consistency
**Ozzie (Player Experience)**
- `subagent_type`: `ozzie`, `model`: `sonnet`
- Prompt: Include the changed files and commit log. Ask Ozzie to review for:
- Emotional impact — does the audio enhance the moment?
- Atmosphere and tone — does it feel like the Commonwealth?
- Player feedback clarity — can the player tell what just happened?
- Pacing — do sounds support or fight the gameplay rhythm?
- Memorable moments — will players remember these audio cues?
.claude/skills/search-docs/SKILL.md
+13 -64
View File
@@ -10,82 +10,39 @@ allowed-tools: Bash, Read, Grep, Glob
# Search Docs Skill # Search Docs Skill
Semantic search across Commonwealth project documents using Qdrant vector database and ollama embeddings. Semantic search across project documents. Basic commands (`qdrant-search`,
`qdrant-index`, `qdrant-health`, `qdrant-count`) and endpoints are documented
in CLAUDE.md. This skill covers advanced operations and workflows.
## Access Method ## Advanced Commands
**Use the connector wrapper scripts:**
```bash
db/connectors/qdrant-search "query text"
db/connectors/qdrant-index <file>
db/connectors/qdrant-health
db/connectors/qdrant-count
```
Or the Python script directly:
```bash
python3 db/connectors/qdrant_connector.py <command> [args]
```
## Commands
### Search
Find documents semantically related to a query:
```bash
db/connectors/qdrant-search "asymmetric information design"
db/connectors/qdrant-search "what did we decide about fog of war"
db/connectors/qdrant-search "engine requirements"
```
Returns top 5 matching document chunks with source file, heading, and relevance score.
### Index a file
Add or update a document in the search index:
```bash
db/connectors/qdrant-index decisions/architecture.md
db/connectors/qdrant-index decisions/perception.md
db/connectors/qdrant-index docs/discussions/round-10-map-fog-borderless.md
db/connectors/qdrant-index docs/briefings/tyre.md
```
Files are chunked by markdown headings (# and ##). Each chunk is embedded via ollama and stored in Qdrant with metadata (source_file, heading, chunk_index).
### Index a single chunk ### Index a single chunk
For precise indexing of specific content: For precise indexing of specific content:
```bash ```bash
python3 db/connectors/qdrant_connector.py index "unique-id" "Text content to index" --metadata source=manual heading="Custom heading" python3 db/connectors/qdrant_connector.py index "unique-id" "Text content to index" --metadata source=manual heading="Custom heading"
``` ```
### Health check
Verify connectivity to Qdrant and ollama:
```bash
db/connectors/qdrant-health
```
### Collection info
Check how many documents are indexed:
```bash
db/connectors/qdrant-count
```
### Create collection ### Create collection
Initialize the Qdrant collection (run once during setup): Initialize the Qdrant collection (run once during setup):
```bash ```bash
python3 db/connectors/qdrant_connector.py create-collection python3 db/connectors/qdrant_connector.py create-collection
``` ```
## Endpoints ## Bulk Indexing
Configured in `db/connectors/config.json`: Index all project documents at once:
- **Qdrant:** `http://tower-of-joy:6333` ```bash
- **Ollama:** `http://tower-of-joy:11434` (model: nomic-embed-text) for f in decisions/*.md DISCUSSION.md TEAM.md docs/discussions/*.md docs/briefings/*.md; do
- **Collection:** `commonwealth` (768 dimensions, cosine distance) db/connectors/qdrant-index "$f"
done
```
## Fallback ## Fallback
If Qdrant or ollama is unreachable, fall back to grep-based search: If Qdrant or ollama is unreachable, fall back to grep-based search:
```bash ```bash
# Search across all project docs
grep -r -i "search term" decisions/ DISCUSSION.md docs/ --include="*.md" grep -r -i "search term" decisions/ DISCUSSION.md docs/ --include="*.md"
``` ```
@@ -96,11 +53,3 @@ grep -r -i "search term" decisions/ DISCUSSION.md docs/ --include="*.md"
3. After briefing updates, re-index affected briefings 3. After briefing updates, re-index affected briefings
4. After decision changes, re-index the relevant decisions/*.md domain files 4. After decision changes, re-index the relevant decisions/*.md domain files
5. Use search to answer "did we discuss this?" questions with citations 5. Use search to answer "did we discuss this?" questions with citations
## Bulk indexing
To index all project documents at once:
```bash
for f in decisions/*.md DISCUSSION.md TEAM.md docs/discussions/*.md docs/briefings/*.md; do
db/connectors/qdrant-index "$f"
done
```
.claude/skills/ticket/SKILL.md
+9 -26
View File
@@ -10,39 +10,17 @@ allowed-tools: Bash, Read, Grep, Glob
# Ticket Skill # Ticket Skill
Manage the project ticketing database (shared `settledreach.db` in the worktree parent directory). Manage the project ticketing database. Basic usage (`ticket list`, `ticket show`,
`ticket sprint --active`) and raw SQL wrappers are documented in CLAUDE.md.
## Access Method This skill covers the full command reference.
**Use the `ticket` CLI for all ticket operations:**
```bash
db/connectors/ticket <command> [args...]
db/connectors/ticket --help
```
All output is JSON on stdout.
For raw SQL access (rare), use the wrapper scripts:
| Script | Purpose |
|--------|---------|
| `db/connectors/sqlite-query "<SQL>"` | Run SELECT queries |
| `db/connectors/sqlite-exec "<SQL>"` | Run INSERT/UPDATE/DELETE |
| `db/connectors/sqlite-init` | Create/update database from schema |
| `db/connectors/sqlite-seed` | Seed initiatives from DECISIONS.md |
## Commands ## Commands
### List tickets ### List tickets (full flags)
```bash ```bash
db/connectors/ticket list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A] [--team T] db/connectors/ticket list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A] [--team T]
``` ```
### Show ticket detail
```bash
db/connectors/ticket show <id>
```
Returns full ticket with children, blockers, and dependents.
### Create ticket ### Create ticket
```bash ```bash
db/connectors/ticket create <type> <title> [--parent N] [--priority P] [--decision D] [--team T] db/connectors/ticket create <type> <title> [--parent N] [--priority P] [--decision D] [--team T]
@@ -88,6 +66,11 @@ db/connectors/ticket children <id>
db/connectors/ticket count [--status S] db/connectors/ticket count [--status S]
``` ```
### Batch show
```bash
db/connectors/ticket show --brief <id> [<id>...]
```
## Workflow ## Workflow
1. **SI (Project Manager)** is the primary user of this skill 1. **SI (Project Manager)** is the primary user of this skill