NCP

Appearance

FileWatcher: Dynamic Discovery of Skills and Photons ​

Overview ​

The FileWatcher enables automatic discovery and indexing of skills and photons without requiring NCP to restart. When you add, modify, or delete skill/photon files, NCP immediately detects and makes them available.

This replaces the old workflow where you had to restart NCP to use newly added skills and photons.

How It Works ​

  1. File Monitoring: FileWatcher continuously monitors:

    • ~/.ncp/skills/ directory for skill changes
    • ~/.ncp/photons/ directory for photon changes (if Photon runtime is enabled)

  2. Event Detection: When files are added, modified, or deleted:

    • Event is debounced to prevent duplicate processing
    • Temporary/system files are automatically filtered out
    • Orchestrator is notified via callbacks

  3. Index Update: Skills/photons are:

    • Loaded and parsed
    • Added to discovery index
    • Made available to Claude immediately
    • Execution time tracked and logged

Configuration ​

Environment Variables ​

NCP_ENABLE_SKILLS (default: true) ​

Enables skill discovery. Set to false to disable skills:

bash
export NCP_ENABLE_SKILLS=false

NCP_ENABLE_PHOTON_RUNTIME (default: true) ​

Enables photon runtime. Set to false if you need to temporarily disable photons:

bash
export NCP_ENABLE_PHOTON_RUNTIME=false
  • CLI / npm installs: Update ~/.ncp/settings.json (enablePhotonRuntime) to make the change stick across shells.
  • DXT / client bundles: These builds ignore ~/.ncp/settings.json, so specify the env var in your client config ("NCP_ENABLE_PHOTON_RUNTIME": "true").

Note: FileWatcher only starts if at least one of these is enabled.

NCP_FILE_WATCHER_DEBOUNCE_MS (default: 300) ​

Debounce interval in milliseconds. Prevents rapid file changes from triggering multiple updates:

bash
export NCP_FILE_WATCHER_DEBOUNCE_MS=500  # 500ms debounce
  • Lower values (100-200ms): More responsive, but higher CPU usage
  • Higher values (500-1000ms): Less responsive, but more stable with slow editors
  • Default (300ms): Good balance for most use cases

Usage Examples ​

Adding a New Skill ​

  1. Create skill directory and file:
bash
mkdir -p ~/.ncp/skills/my-skill
echo "# My Skill" > ~/.ncp/skills/my-skill/SKILL.md
  1. NCP automatically detects it:
⭐ Skill added (auto-detected): my-skill
✅ Skill indexed: my-skill (125ms)
  1. Skill is immediately available to Claude without restart

Modifying an Existing Skill ​

  1. Edit the SKILL.md file:
bash
nano ~/.ncp/skills/my-skill/SKILL.md
  1. NCP automatically detects the change:
🔄 Skill modified (auto-detected): my-skill
✅ Skill updated: my-skill (142ms)
  1. Updated version available immediately

Removing a Skill ​

  1. Delete the skill directory:
bash
rm -rf ~/.ncp/skills/my-skill
  1. NCP automatically detects removal:
🗑️  Skill removed (auto-detected): my-skill
✅ Skill unindexed: my-skill
  1. Skill no longer available to Claude

File Filtering ​

FileWatcher automatically ignores:

  • Editor backups: ~, .swp, .swo, .bak
  • Temp files: .tmp, .orig
  • macOS: ._*, .DS_Store
  • Windows: Thumbs.db
  • Office: ~123 (Word/Excel backups)

These are silently ignored and don't trigger updates.

Logging ​

Log Levels ​

Enable detailed logging to debug FileWatcher:

bash
export NCP_DEBUG=true

Log Messages ​

Different emoji indicators show operation type:

  • ⭐: File added (new detection)
  • 🔄: File modified (update detection)
  • 🗑️: File deleted (removal detection)
  • ✅: Operation succeeded
  • ❌: Operation failed
  • 📁: FileWatcher startup/shutdown

Example Log Output ​

📁 File watcher started for skills and photons directories (debounce: 300ms)
⭐ Skill added (auto-detected): my-skill
✅ Skill indexed: my-skill (125ms)
🔄 Skill modified (auto-detected): my-skill
✅ Skill updated: my-skill (142ms)
🗑️  Skill removed (auto-detected): my-skill
✅ Skill unindexed: my-skill

Troubleshooting ​

FileWatcher Not Detecting Changes ​

Symptom: Files added but not appearing in NCP

Causes & Solutions:

  1. Skills are disabled:

    bash
    # Check if enabled (should be 'true')
echo $NCP_ENABLE_SKILLS

# Enable if disabled
export NCP_ENABLE_SKILLS=true

  2. Photon runtime disabled (for photons):

    bash
    # Enable photon runtime
export NCP_ENABLE_PHOTON_RUNTIME=true

  3. File in wrong location:

    • Skills must be in ~/.ncp/skills/
    • Photons must be in ~/.ncp/photons/
    • Use full paths: ~ expands to your home directory

  4. File not matching expected format:

    • Skills: Directory with SKILL.md file
    • Photons: Files ending in .photon.ts or .photon.js

  5. Editor hasn't saved file:

    • FileWatcher only detects saved changes
    • Ensure file is fully saved before checking logs

Updates Taking Too Long ​

Symptom: Skill/photon updates are slow (>1-2 seconds)

Possible Causes:

  1. Debounce interval too high:

    bash
    # Reduce debounce (but watch for duplicates)
export NCP_FILE_WATCHER_DEBOUNCE_MS=200

  2. Slow filesystem:

    • Updates are slower on network shares or cloud storage
    • Consider using local filesystem for .ncp/ directory

  3. Large skill/photon files:

    • Parsing large files takes time
    • Consider splitting into smaller files

FileWatcher Not Starting ​

Symptom: No "File watcher started" message in logs

Possible Causes:

  1. Both features disabled:

    bash
    # At least one must be enabled
export NCP_ENABLE_SKILLS=true

  2. NCP not initialized yet:

    • FileWatcher starts during background initialization
    • Wait for "MCP server ready" message

  3. File system permissions:

    bash
    # Check directory is readable
ls -la ~/.ncp/skills/
ls -la ~/.ncp/photons/

Duplicate Updates ​

Symptom: Same skill updated multiple times for single change

Cause: Debounce interval too low, editor creates multiple save events

Solution:

bash
# Increase debounce to reduce duplicates
export NCP_FILE_WATCHER_DEBOUNCE_MS=500

Performance Considerations ​

Memory Usage ​

FileWatcher uses minimal memory:

  • Per-file debounce timers: ~1KB each
  • Watcher instances: ~2MB total
  • No significant impact on NCP's memory footprint

CPU Usage ​

FileWatcher has minimal CPU impact:

  • Idle state: <0.1% CPU
  • Processing updates: <1% CPU per update
  • Debounce prevents rapid processing

Filesystem Impact ​

FileWatcher uses OS-level file monitoring:

  • macOS: Uses FSEvents (efficient)
  • Linux: Uses inotify (efficient)
  • Windows: Uses file system watcher API (efficient)

No polling or scanning required.

Best Practices ​

1. Use Local Filesystem ​

Avoid:

  • Network shares (NFS, SMB)
  • Cloud-synced folders (Dropbox, OneDrive, iCloud)
  • Virtual filesystems

These can have delayed file change detection.

2. One SKILL.md Per Directory ​

✅ Good:

~/.ncp/skills/
  └─ my-skill/
     └─ SKILL.md

❌ Bad:

~/.ncp/skills/
  └─ SKILL.md  (ambiguous - what's the skill name?)

3. Use Consistent File Extensions ​

✅ Good:

my-photon.photon.ts
my-photon.photon.js

❌ Bad:

my-photon.ts (missing .photon marker)

4. Let Editor Fully Save ​

Always ensure files are fully saved:

  • VSCode: Wait for white dot to disappear from tab
  • Vim: Confirm :w command completes
  • Don't force-save in middle of write

5. Check Logs When Adding Skills ​

Always verify the skill was detected:

bash
# Look for success message
tail -50 ~/.ncp/logs/ncp.log | grep -i "skill.*indexed"

Advanced Configuration ​

Custom Debounce Per Skill ​

Currently not supported, but can be achieved by:

  1. Temporarily increase debounce for bulk operations
  2. Return to normal debounce for regular use
bash
# Bulk add multiple skills
export NCP_FILE_WATCHER_DEBOUNCE_MS=1000
# ...copy/add many skill files...
# Then reduce back for normal use
export NCP_FILE_WATCHER_DEBOUNCE_MS=300

Monitoring FileWatcher Events ​

To track all file changes:

bash
export NCP_DEBUG=true
tail -f ~/.ncp/logs/ncp.log | grep -E "⭐|🔄|🗑️|❌"

FAQ ​

Q: Does FileWatcher require a restart? A: No! That's the whole point - NCP keeps running and detects changes automatically.

Q: Can I disable FileWatcher but keep skills enabled? A: Currently no - if skills are enabled, FileWatcher will start. This is by design to ensure consistency.

Q: What if I'm editing a skill and someone else is too? A: The last save wins. FileWatcher detects the final modification and indexes that version. Consider using version control for collaboration.

Q: How long does a skill update take? A: Typically 100-300ms, depending on:

  • File size
  • Filesystem speed
  • System load
  • Debounce interval

Q: Can I use network shares for ~/.ncp/? A: Not recommended. Network latency causes delayed change detection. Use local filesystem for best results.

Q: What happens if a skill has syntax errors? A: The update fails with an error message. Previous version remains in index. Fix the error and re-save to update.

Q: Do deleted skills clean up immediately? A: Yes. Deletion removes the skill from discovery index immediately (within debounce window).

See Also ​

Released under the Elastic License 2.0.

Copyright Portel