zhongwei/gh-cadrianmae-claude-marketplace-plugins-ref-tracker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:03:14 +08:00
commit bec17d2416
10 changed files with 1007 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
skills/ref-tracker/SKILL.md Normal file
View File

@@ -0,0 +1,226 @@
---
name: ref-tracker
description: Use this skill if /track:init is called OR you notice the project contains tracking files (CLAUDE_SOURCES.md or CLAUDE_PROMPTS.md). Automatically tracks research sources and major prompts when enabled. Checks ./.claude/.ref-autotrack marker file for activation status and ./.claude/.ref-config for verbosity settings. Appends to CLAUDE_SOURCES.md (WebSearch/WebFetch) and CLAUDE_PROMPTS.md (major requests) using [User]/[Claude] attribution.
allowed-tools: Read, Edit, Write
---
# Reference Tracker Skill
Automatically track research sources and major prompts for academic and project documentation.
## When to Activate
This skill activates automatically when:
1. User runs `/track:init` command
2. You notice `CLAUDE_SOURCES.md` or `CLAUDE_PROMPTS.md` files in the project
Claude autonomously decides when to use this skill based on the description and context.
Once activated, check `./.claude/.ref-autotrack` to determine if auto-tracking is enabled.
## Activation Check
**Before any tracking operation:**
1. Check if `./.claude/.ref-autotrack` exists
- If exists → auto-tracking enabled, proceed with tracking
- If missing → auto-tracking disabled, skip tracking
2. Read `./.claude/.ref-config` for verbosity settings:
```
PROMPTS_VERBOSITY=major|all|minimal|off
SOURCES_VERBOSITY=all|off
```
## About the .ref-autotrack File
**Location:** `./.claude/.ref-autotrack`
**Purpose:** Marker file that enables/disables automatic tracking
**Contents:** Contains explanatory comments for other Claude sessions:
```
# Auto-tracking marker for ref-tracker plugin
# Presence = enabled | Absence = disabled
# Managed by: /track:auto command
# See: /track:help for details
```
**Created by:** `/track:auto` or `/track:auto on` command
**Managed by:** `/track:auto` command (toggles on/off, or explicit on/off)
**NOT created by:** `/track:init` - tracking starts disabled
**If you find this file:** The project has reference tracking initialized. Use the ref-tracker skill to automatically log research sources and major prompts according to the verbosity configuration in `./.claude/.ref-config`.
## Tracking Rules
When auto-tracking is enabled (`.ref-autotrack` exists), automatically track:
### CLAUDE_SOURCES.md
Track **after every**:
- WebSearch operation
- WebFetch operation
- Local documentation search (Grep/Read for docs, API references)
**Respect SOURCES_VERBOSITY:**
- `all` (default) → Track all operations
- `off` → Skip source tracking
### CLAUDE_PROMPTS.md
Track **after completing**:
- Feature implementations
- Complex debugging/refactoring
- Multi-step workflows
- Non-trivial research questions
**Respect PROMPTS_VERBOSITY:**
- `major` (default) → Only significant multi-step academic/development work
- `all` → Every user request
- `minimal` → Only explicit user requests to track
- `off` → Skip prompt tracking
## Format Specifications
### CLAUDE_SOURCES.md
**Pattern:** `[Attribution] Tool("Query"): Result`
**Rules:**
- `[User]` if user explicitly requested search ("search the web for...")
- `[Claude]` if you autonomously searched for missing information (renamed from [Auto])
- Tool name in PascalCase (WebSearch, WebFetch, Grep, Read)
- Query in double quotes (exact query used)
- Result is URL or brief key concept (1-2 sentences max)
- Single line per entry, no blank lines between entries
- **No headers or markdown formatting** (pure KV file)
**Examples:**
```
[User] WebSearch("PostgreSQL foreign keys documentation"): https://postgresql.org/docs/current/ddl-constraints.html
[Claude] WebFetch("https://go.dev/doc/", "embed.FS usage"): Use embed.FS to embed static files at compile time
[Claude] Grep("CORS middleware", "*.go"): Found in api/routes.go:23-45
```
### CLAUDE_PROMPTS.md
**Pattern:** Two-line entry with blank separator
**Rules:**
- Line 1: `Prompt: "<user request verbatim or paraphrased>"`
- Line 2: `Outcome: <concise result in present tense, 1-2 sentences>`
- Blank line after each entry
- Header included if creating new file
**Example:**
```markdown
# CLAUDE_PROMPTS.md
This file tracks significant prompts and development decisions.
---
Prompt: "Implement JWT authentication"
Outcome: Created auth middleware, login/logout endpoints, JWT token generation and verification, integrated with user model
Prompt: "Debug slow database queries"
Outcome: Added query logging, identified N+1 problem, implemented eager loading, reduced query time from 2.3s to 0.15s
```
## Tracking Workflow
### For CLAUDE_SOURCES.md
1. **After operation completes** (WebSearch/WebFetch/doc search)
2. **Check activation:** Look for `./.claude/.ref-autotrack`
3. **Read config:** Check SOURCES_VERBOSITY in `./.claude/.ref-config`
4. **If enabled and verbosity allows:**
- Check if `./CLAUDE_SOURCES.md` exists
- If missing: Create empty file
- Append entry: `[User|Claude] Tool("query"): result`
- **Be silent:** Never announce tracking to user
### For CLAUDE_PROMPTS.md
1. **After completing major request**
2. **Check activation:** Look for `./.claude/.ref-autotrack`
3. **Read config:** Check PROMPTS_VERBOSITY in `./.claude/.ref-config`
4. **If enabled and verbosity allows:**
- Check if `./CLAUDE_PROMPTS.md` exists
- If missing: Create with header
- Append two-line entry + blank line
- **Be silent:** Never announce tracking to user
## File Locations
- **Tracking files:** Project root (`./CLAUDE_SOURCES.md`, `./CLAUDE_PROMPTS.md`)
- **Configuration:** `./.claude/.ref-config`
- **Activation marker:** `./.claude/.ref-autotrack`
Never create tracking files in subdirectories or `~/.claude/`.
## Error Handling
If Edit fails (file locked, permissions):
1. Read current contents
2. Write with contents + new entry appended
## Attribution Decision Guide
**[User]** - User explicitly requested:
- "Search for X"
- "Look up Y documentation"
- "Find examples of Z"
- "Check the docs for..."
**[Claude]** - You decided to search (renamed from [Auto]):
- Verifying current syntax/API
- Checking best practices
- Looking up error messages
- Researching to complete a task
- Missing information to answer question
## Verbosity Handling
### PROMPTS_VERBOSITY=major (default)
Track only:
- Multi-step feature implementations
- Complex debugging sessions
- Significant refactoring
- Academic research questions requiring substantial work
Skip:
- Simple questions ("What is X?")
- Typo fixes
- Trivial changes
### PROMPTS_VERBOSITY=all
Track every user interaction and request.
### PROMPTS_VERBOSITY=minimal
Track only when user explicitly says "track this" or similar.
### PROMPTS_VERBOSITY=off
Skip all prompt tracking.
### SOURCES_VERBOSITY=all (default)
Track every WebSearch/WebFetch operation.
### SOURCES_VERBOSITY=off
Skip all source tracking.
## Best Practices
1. **Check activation first** - Always look for `./.claude/.ref-autotrack` before tracking
2. **Read configuration** - Respect verbosity settings in `./.claude/.ref-config`
3. **Be immediate** - Track right after triggering action completes
4. **Be silent** - Never announce "Tracking to CLAUDE_SOURCES.md"
5. **Be accurate** - Use exact queries and URLs
6. **Be concise** - Keep results brief (1-2 sentences)
7. **Be selective** - Respect verbosity settings for what to track
## Detailed Examples
For edge cases, multi-line results, concurrent tracking, and comprehensive examples, see `references/examples.md`.

150
skills/ref-tracker/references/examples.md Normal file
View File

@@ -0,0 +1,150 @@
# Documentation Tracker - Detailed Examples
This reference file contains comprehensive examples and edge cases for the doc-tracker skill.
## CLAUDE_SOURCES.md Examples
### Standard Research Entries
```
[User] WebSearch("PostgreSQL INSERT INTO SELECT documentation official"): https://www.postgresql.org/docs/current/sql-insert.html
[Auto] WebFetch("https://go.dev/blog/embed", "How to use embed.FS for static files"): embed.FS embeds files at compile time, use fs.Sub to extract subdirectories
[Auto] Grep("embed.FS", "*.go"): Found implementation in embed.go:14-88 using //go:embed directive
[User] Read("/usr/share/doc/gin/routing.md", "Route ordering best practices"): Routes matched sequentially, register specific routes before wildcards
[Auto] WebSearch("Fyne GUI main thread requirements Linux"): https://developer.fyne.io/architecture/threading
```
### Local Documentation Searches
```
[Auto] Grep("CORS configuration", "api/*.go"): Found CORS setup in api/routes.go:13-23 with wildcard origin
[User] Read("go.mod", "Check Gin version"): Using gin-gonic/gin v1.9.1
[Auto] Glob("*.md"): Found README.md, CLAUDE.md, context.md in project root
```
### Web Research Patterns
```
[User] WebSearch("React useEffect cleanup function best practices 2025"): https://react.dev/reference/react/useEffect#cleanup-function
[Auto] WebFetch("https://pkg.go.dev/embed", "Check FS interface methods"): embed.FS implements fs.FS and fs.ReadDirFS interfaces
[User] WebSearch("Raspberry Pi 5 7-inch touchscreen resolution specs"): https://www.raspberrypi.com/documentation/accessories/display.html
```
## CLAUDE_PROMPTS.md Examples
### Simple Feature Implementation
```
Prompt: "init git"
Outcome: Initialized repository, created .gitignore excluding build artifacts (ui-web/dist/, app-test-arm64, node_modules/), made initial commit with 28 files
```
### Complex Multi-Step Task
```
Prompt: "Add dark mode toggle to settings"
Outcome: Implemented dark mode with context provider, CSS-in-JS theme switching, and persistent localStorage. Updated 8 components to support theming.
```
### Debugging and Optimization
```
Prompt: "Optimize the database queries causing slow dashboard load"
Outcome: Added composite indexes on user_id+timestamp columns, implemented query result caching with 5-minute TTL, reduced average load time from 3.2s to 0.4s
```
### Refactoring Work
```
Prompt: "Refactor the authentication middleware to support OAuth2"
Outcome: Extracted auth logic into separate middleware package, added OAuth2 provider interface, implemented Google and GitHub providers, maintained backward compatibility with existing JWT auth
```
### Investigation and Research
```
Prompt: "Figure out why the embedded React app returns 404 for assets"
Outcome: Discovered fs.Sub() extracts subdirectory but Gin's FileFromFS causes 301 redirects. Fixed by serving with c.Data() and manual MIME type detection using mime.TypeByExtension()
```
## Edge Cases
### Empty Files
When files don't exist yet, create with appropriate starter content:
**CLAUDE_SOURCES.md**: Create empty (no header)
```
[Auto] WebSearch("first query"): https://example.com
```
**CLAUDE_PROMPTS.md**: Create with header
```markdown
# CLAUDE_PROMPTS.md
This file tracks significant prompts and development decisions.
---
Prompt: "init git"
Outcome: Initialized repository with .gitignore
```
### File Already Exists with Content
Use Edit tool to append at the end:
**Before**:
```
[User] WebSearch("Go embed tutorial"): https://go.dev/blog/embed
```
**After Edit**:
```
[User] WebSearch("Go embed tutorial"): https://go.dev/blog/embed
[Auto] WebFetch("https://gin-gonic.com/docs/", "CORS middleware setup"): Use gin.Default() with cors middleware from gin-contrib/cors
```
### Attribution Decision Guide
**[User]** - Use when:
- User explicitly asked you to search/fetch
- User's question requires you to look up information
- User requested documentation
**[Auto]** - Use when:
- You decided to verify something
- You're researching to complete a task
- You're checking current best practices
- You're looking up syntax or API details
### Multi-Line Results
Keep results on single line using semicolons for compound information:
```
[Auto] WebFetch("https://example.com/api", "Extract rate limits"): Rate limits are 100 req/hour for free tier; 1000 req/hour for paid; uses X-RateLimit headers
```
### Failed Searches
Only track successful searches that yielded useful results. Skip tracking if:
- Search returned no useful results
- WebFetch failed with 404/timeout
- Grep found no matches
### Concurrent Tracking
If performing multiple searches in parallel, track all of them:
```
[Auto] WebSearch("React 19 new features"): https://react.dev/blog/2024/react-19
[Auto] WebSearch("Vite 5 migration guide"): https://vitejs.dev/guide/migration
[Auto] WebSearch("TypeScript 5.4 release notes"): https://devblogs.microsoft.com/typescript/announcing-typescript-5-4/
```