feat: Add search skill with progressive disclosure and refactor existing skills
Enhancements: - Added search skill with 10 HTTP API endpoints for memory queries - Refactored version-bump and troubleshoot skills using progressive disclosure pattern - Added operations/ subdirectories for detailed skill documentation - Updated CLAUDE.md with skill-based search architecture - Enhanced worker service with search API endpoints - Updated CHANGELOG.md with v5.4.0 migration details Technical changes: - New plugin/skills/search/ directory with SKILL.md - New .claude/skills/version-bump/operations/ (workflow.md, scenarios.md) - New plugin/skills/troubleshoot/operations/ (common-issues.md, worker.md) - Modified src/services/worker-service.ts (added search endpoints) - Modified plugin/scripts/worker-service.cjs (rebuilt with search API) - Reduced main skill files by 89% using progressive disclosure - Token savings: ~2,250 tokens per session start 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Alex Newman
@@ -0,0 +1,242 @@
|
||||
# Response Formatting Guidelines
|
||||
|
||||
How to present search results to users.
|
||||
|
||||
## Format=Index Responses
|
||||
|
||||
When using `format=index`, present results as a **compact list**.
|
||||
|
||||
### Observations
|
||||
|
||||
```markdown
|
||||
Found 5 results for "authentication":
|
||||
|
||||
1. **#1234** [feature] Implemented JWT authentication
|
||||
> Added token-based auth with refresh tokens
|
||||
> Nov 9, 2024 • claude-mem
|
||||
|
||||
2. **#1235** [bugfix] Fixed token expiration edge case
|
||||
> Handled race condition in refresh flow
|
||||
> Nov 9, 2024 • claude-mem
|
||||
|
||||
3. **#1236** [refactor] Simplified authentication middleware
|
||||
> Reduced code complexity by 40%
|
||||
> Nov 10, 2024 • claude-mem
|
||||
```
|
||||
|
||||
**Include:**
|
||||
- ID (for follow-up queries)
|
||||
- Type with emoji (see below)
|
||||
- Title
|
||||
- Subtitle (one-line summary)
|
||||
- Date and project
|
||||
|
||||
**Type Emojis:**
|
||||
- 🔴 **bugfix**: Bug fixes
|
||||
- 🟣 **feature**: New features
|
||||
- 🔄 **refactor**: Code restructuring
|
||||
- 🧠 **decision**: Architectural decisions
|
||||
- 🔵 **discovery**: Learnings
|
||||
- ✅ **change**: General changes
|
||||
|
||||
### Sessions
|
||||
|
||||
```markdown
|
||||
Found 3 sessions about "deployment":
|
||||
|
||||
1. **Session #123** (Nov 8, 2024)
|
||||
> Deploy Docker container to production
|
||||
> Completed: Set up CI/CD pipeline, configured secrets
|
||||
|
||||
2. **Session #124** (Nov 9, 2024)
|
||||
> Fix deployment rollback issues
|
||||
> Completed: Added health checks, fixed rollback script
|
||||
```
|
||||
|
||||
### Prompts
|
||||
|
||||
```markdown
|
||||
Found 3 past prompts about "docker":
|
||||
|
||||
1. **Prompt #456** (Nov 8, 2024)
|
||||
> "Help me set up Docker for this project"
|
||||
|
||||
2. **Prompt #457** (Nov 9, 2024)
|
||||
> "Fix Docker compose networking issues"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Format=Full Responses
|
||||
|
||||
When using `format=full`, present **complete details**.
|
||||
|
||||
### Observations (Full)
|
||||
|
||||
```markdown
|
||||
### Observation #1234: Implemented JWT authentication
|
||||
|
||||
**Type:** Feature 🟣
|
||||
**Project:** claude-mem
|
||||
**Date:** Nov 9, 2024 3:30 PM
|
||||
|
||||
**Summary:** Added token-based auth with refresh tokens
|
||||
|
||||
**Details:**
|
||||
Implemented a complete JWT authentication system for the API. The system uses
|
||||
short-lived access tokens (15 minutes) combined with longer-lived refresh tokens
|
||||
(7 days) to balance security and user experience. The implementation includes
|
||||
middleware for route protection and automatic token refresh handling.
|
||||
|
||||
**Facts:**
|
||||
- Used jsonwebtoken library (v9.0.2)
|
||||
- Access tokens expire after 15 minutes
|
||||
- Refresh tokens expire after 7 days
|
||||
- Tokens include user ID and role claims
|
||||
- Added rate limiting to auth endpoints
|
||||
|
||||
**Files Modified:**
|
||||
- src/auth/jwt.ts (created, 145 lines)
|
||||
- src/middleware/auth.ts (created, 78 lines)
|
||||
- src/routes/auth.ts (created, 92 lines)
|
||||
- tests/auth.test.ts (created, 234 lines)
|
||||
|
||||
**Concepts:** authentication, security, tokens, middleware
|
||||
```
|
||||
|
||||
### Sessions (Full)
|
||||
|
||||
```markdown
|
||||
### Session #123: Add user authentication (Nov 8, 2024)
|
||||
|
||||
**Request:** Implement JWT-based authentication for the API
|
||||
|
||||
**Completed:**
|
||||
- Implemented JWT authentication system with access and refresh tokens
|
||||
- Created authentication middleware for route protection
|
||||
- Added login, logout, and token refresh endpoints
|
||||
- Wrote comprehensive tests for auth flows
|
||||
- Added rate limiting to prevent brute force attacks
|
||||
|
||||
**Learned:**
|
||||
- JWT refresh token rotation is critical for security
|
||||
- Need to handle token expiration gracefully on client side
|
||||
- Rate limiting should be IP-based for auth endpoints
|
||||
- Token blacklisting adds complexity, short expiration is simpler
|
||||
|
||||
**Next Steps:**
|
||||
- Add password reset functionality
|
||||
- Implement 2FA for admin accounts
|
||||
- Add OAuth integration for social login
|
||||
|
||||
**Files Read:**
|
||||
- docs/authentication-spec.md
|
||||
- src/middleware/existing-auth.ts
|
||||
- tests/integration/auth.test.ts
|
||||
|
||||
**Files Edited:**
|
||||
- src/auth/jwt.ts (created)
|
||||
- src/middleware/auth.ts (created)
|
||||
- src/routes/auth.ts (created)
|
||||
- tests/auth.test.ts (created)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Timeline Responses
|
||||
|
||||
Present timeline results **chronologically grouped by day**.
|
||||
|
||||
```markdown
|
||||
## Timeline around Observation #1234
|
||||
|
||||
**Window:** 10 records before → 10 records after
|
||||
**Total:** 15 items (8 obs, 5 sessions, 2 prompts)
|
||||
|
||||
### Nov 8, 2024
|
||||
|
||||
**4:30 PM** - 🎯 **Session Request:** "Add user authentication"
|
||||
|
||||
**4:45 PM** - 🔵 **Discovery #1230:** "JWT library options compared"
|
||||
> Evaluated 3 libraries: jsonwebtoken, jose, passport-jwt
|
||||
> Chose jsonwebtoken for simplicity and community support
|
||||
|
||||
**5:00 PM** - 🧠 **Decision #1231:** "Chose jsonwebtoken for simplicity"
|
||||
> jsonwebtoken has better TypeScript support and simpler API
|
||||
|
||||
**5:15 PM** - 🟣 **Feature #1232:** "Created JWT utility functions"
|
||||
> Sign, verify, and decode token helpers
|
||||
|
||||
### Nov 9, 2024
|
||||
|
||||
**3:30 PM** - 🟣 **Feature #1234:** "Implemented JWT authentication" ← ANCHOR
|
||||
> Complete auth system with access and refresh tokens
|
||||
|
||||
**4:00 PM** - 🔴 **Bugfix #1235:** "Fixed token expiration edge case"
|
||||
> Handled race condition in refresh flow
|
||||
|
||||
**4:30 PM** - ✅ **Change #1236:** "Updated API documentation"
|
||||
> Added auth endpoint docs to README
|
||||
```
|
||||
|
||||
**Legend:**
|
||||
- 🎯 session-request
|
||||
- 🔴 bugfix
|
||||
- 🟣 feature
|
||||
- 🔄 refactor
|
||||
- ✅ change
|
||||
- 🔵 discovery
|
||||
- 🧠 decision
|
||||
|
||||
**Formatting Rules:**
|
||||
1. Group by day with date headers
|
||||
2. Show time for each item
|
||||
3. Use emoji + type + ID/title
|
||||
4. Indent subtitle/summary with `>`
|
||||
5. Mark anchor point with `← ANCHOR`
|
||||
6. Include legend at bottom
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
### No Results
|
||||
|
||||
```markdown
|
||||
No results found for "foobar". Try different search terms or:
|
||||
- Check spelling
|
||||
- Use broader terms
|
||||
- Try synonyms
|
||||
- Search by type or concept instead
|
||||
```
|
||||
|
||||
### Service Unavailable
|
||||
|
||||
```markdown
|
||||
Search service is not available. The claude-mem worker may not be running.
|
||||
|
||||
To check worker status:
|
||||
\`\`\`bash
|
||||
pm2 list
|
||||
\`\`\`
|
||||
|
||||
To restart the worker:
|
||||
\`\`\`bash
|
||||
pm2 restart claude-mem-worker
|
||||
\`\`\`
|
||||
|
||||
Would you like help troubleshooting?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## General Formatting Tips
|
||||
|
||||
1. **Use markdown formatting**: Bold, headers, code blocks, quotes
|
||||
2. **Be concise**: Users want quick answers, not walls of text
|
||||
3. **Highlight key information**: IDs, dates, types
|
||||
4. **Group related items**: By day, by type, by file
|
||||
5. **Offer follow-ups**: "Want more details?" "See timeline?"
|
||||
6. **Use visual hierarchy**: Headers, lists, indentation
|
||||
7. **Include context**: Project names, dates, related observations
|
||||
8. **Make IDs clickable-ready**: **#1234** stands out for reference
|
||||
Reference in New Issue
Block a user