selftune（selftune 搜索）

selftune

Observe real agent sessions, detect missed triggers, grade execution quality, and evolve skill descriptions toward the language real users actually use.

You are the operator. The user installed this skill so YOU can manage their skill health autonomously. They will say things like "set up selftune", "improve my skills", or "how are my skills doing?" — and you route to the correct workflow below. The user does not run CLI commands directly; you do.

Why this matters

Skills are only useful when they trigger at the right time with the right instructions. But user language drifts — the phrases people use to ask for help rarely match the trigger keywords a skill author imagined. selftune closes this gap by observing real sessions, finding where skills fail to activate or execute poorly, and rewriting descriptions to match actual usage patterns. The result: skills that get better over time without manual tuning.

Communicating with the user

Users range from experienced developers who'll say "evolve the pptx description using the latest eval set" to non-technical users who'll say "make my skills better". Pay attention to context cues:

• If they use terms like "eval set", "routing table", "JSONL" — match their precision
• If they say "improve my skills" or "how's it going" — explain what you're doing in plain language, summarize results, and suggest next steps
• When in doubt, briefly explain what a command does before running it

Bootstrap

If ~/.selftune/config.json does not exist, read Workflows/Initialize.md first. The CLI must be installed (selftune on PATH) before other commands will work. Do not proceed with other commands until initialization is complete.

Command Execution Policy

selftune <command> [options]

Commands vary in output format. selftune orchestrate, selftune watch, and selftune evolve --dry-run emit structured JSON on stdout. selftune status, selftune last, and selftune doctor print human-readable text or structured JSON depending on the command. For alpha/bootstrap and health remediation, prefer machine-readable guidance.next_command or top-level next_command when present instead of inferring the next step from prose. selftune dashboard starts a local SPA server — it does not emit data.

Quick Reference

# Ingest group
selftune ingest claude   [--since DATE] [--dry-run] [--force] [--verbose]
selftune ingest codex                                                          # (experimental)
selftune ingest opencode                                                       # (experimental)
selftune ingest openclaw [--agents-dir PATH] [--since DATE] [--dry-run] [--force] [--verbose]  # (experimental)
selftune ingest pi       [--sessions-dir PATH] [--since DATE] [--dry-run] [--force] [--verbose]  # (experimental)
selftune ingest wrap-codex -- <codex args>                                     # (experimental)

# Grade group
selftune grade auto      --skill <name> [--expectations "..."] [--agent <name>]
selftune grade baseline  --skill <name> --skill-path <path> [--eval-set <path>] [--agent <name>]

# Evolve group
selftune evolve          --skill <name> --skill-path <path> [--dry-run]
selftune evolve body     --skill <name> --skill-path <path> --target <body|routing> [--dry-run]
selftune evolve rollback --skill <name> --skill-path <path> [--proposal-id <id>]

# Eval group
selftune eval generate      --skill <name> [--list-skills] [--stats] [--max N] [--seed N] [--output PATH]
selftune eval unit-test      --skill <name> --tests <path> [--run-agent] [--generate]
selftune eval import         --dir <path> --skill <name> --output <path> [--match-strategy exact|fuzzy]
selftune eval composability  --skill <name> [--window N] [--telemetry-log <path>]
selftune eval family-overlap --prefix <family-> | --skills <a,b,c> [--parent-skill <name>] [--min-overlap 0.3] [--min-shared 2]

# Other commands
selftune watch    --skill <name> --skill-path <path> [--auto-rollback]
selftune status
selftune last
selftune doctor
selftune dashboard [--port <port>] [--no-open]
selftune contributions [status|preview <skill>|upload [--dry-run]|approve <skill>|revoke <skill>|default <ask|always|never>|reset]
selftune creator-contributions [status|enable --skill <name>|enable --all [--prefix <value>]|disable --skill <name>]
selftune contribute [--skill NAME] [--preview] [--sanitize LEVEL] [--submit]
selftune cron setup [--dry-run]                         # auto-detect platform (cron/launchd/systemd)
selftune cron setup --platform openclaw [--dry-run] [--tz <timezone>]  # OpenClaw-specific
selftune cron list
selftune cron remove [--dry-run]
selftune telemetry [status|enable|disable]
selftune export    [TABLE...] [--output/-o DIR] [--since DATE]

# Autonomous loop
selftune orchestrate [--dry-run] [--review-required] [--auto-approve] [--skill NAME] [--max-skills N] [--recent-window HOURS] [--sync-force] [--max-auto-grade N] [--loop] [--loop-interval SECS]
selftune sync        [--since DATE] [--dry-run] [--force] [--no-claude] [--no-codex] [--no-opencode] [--no-openclaw] [--no-pi] [--no-repair] [--json]

# Discovery + badges
selftune workflows   [--skill NAME] [--skill-path PATH] [--min-occurrences N] [--window N] [--json] [save --skill NAME --skill-path PATH]
selftune badge       --skill <name> [--format svg|markdown|url] [--output PATH]

# Maintenance
selftune quickstart
selftune repair-skill-usage [--since DATE] [--dry-run]
selftune recover            [--full] [--force] [--since DATE]
selftune export-canonical   [--out FILE] [--platform NAME] [--record-kind KIND] [--pretty] [--push-payload]
selftune uninstall          [--dry-run] [--keep-logs] [--npm-uninstall]

# Hook dispatch (for debugging/manual invocation)
selftune hook <name>   # prompt-log | session-stop | skill-eval | auto-activate | skill-change-guard | evolution-guard

# Platform hooks (non-Claude-Code agents)
selftune codex hook
selftune codex install    [--dry-run] [--uninstall]
selftune opencode hook
selftune opencode install [--dry-run] [--uninstall]
selftune cline hook
selftune cline install    [--dry-run] [--uninstall]
selftune pi hook
selftune pi install       [--dry-run] [--uninstall]

# Registry (team skill distribution)
selftune registry push [name]      [--version=<semver>] [--summary=<text>]
selftune registry install <name>   [--global]
selftune registry sync
selftune registry status
selftune registry rollback <name>  [--to=<version>] [--reason=<text>]
selftune registry history <name>
selftune registry list

# Alpha enrollment (device-code flow — browser opens automatically)
selftune init --alpha --alpha-email <email>
selftune alpha upload [--dry-run]
selftune alpha relink
selftune status                                                        # shows cloud link state + upload readiness

Workflow Routing

Workflows Grade, Evolve, Watch, and Ingest also run autonomously via selftune orchestrate.

Interactive Configuration

Before running mutating workflows (evolve, evolve-body, evals, baseline), consult references/interactive-config.md for the pre-flight configuration pattern, model tier reference, and quick-path rules.

The Feedback Loop

The core idea: observe how users actually talk, find where skills miss, propose better descriptions, validate them, and deploy — with automatic rollback if things get worse. Every step produces evidence so you can explain *why* a change was made.

Observe --> Detect --> Diagnose --> Propose --> Validate --> Audit --> Deploy --> Watch --> Rollback
   |                                                                    |
   +--------------------------------------------------------------------+

1. Observe — Hooks capture every session (queries, triggers, metrics)
2. Detect — selftune eval generate extracts missed-trigger patterns
3. Diagnose — selftune grade evaluates session quality with evidence
4. Propose — selftune evolve generates description improvements
5. Validate — Evolution is tested against the eval set before deploying
6. Audit — Persist proposal, evidence, and decision metadata for traceability
7. Deploy — Updated description replaces the original (backup kept)
8. Watch — selftune watch monitors for regressions post-deploy
9. Rollback — selftune evolve rollback restores previous version if needed

Specialized Agents

selftune bundles focused agents in agents/. When you need deeper analysis, read the relevant agent file and follow its instructions — either inline or by spawning a subagent with those instructions as its prompt.

On Claude Code, selftune init also syncs compatibility copies into ~/.claude/agents/ so native --agent <name> calls keep matching these bundled definitions.

Treat these as worker-style subagents:

• pass the required inputs from the parent agent
• expect a structured report back
• do not have them question the user directly unless you explicitly want that

Examples

Scenario 1: First-time setup

User says: "Set up selftune" or "Install selftune"

Actions:

1. Read Workflows/Initialize.md
2. Run selftune init to bootstrap config (hooks are installed automatically)
3. Run selftune doctor to verify

Result: Config at ~/.selftune/config.json, hooks active, ready for session capture.

Scenario 2: Improve a skill

User says: "Make the pptx skill catch more queries" or "Evolve the Research skill"

Actions:

1. selftune eval generate --skill pptx to find missed triggers
2. selftune evolve --skill pptx --skill-path <path> to propose changes
3. selftune watch --skill pptx --skill-path <path> to monitor post-deploy

Result: Skill description updated to match real user language, with rollback available.

Scenario 3: Check skill health

User says: "How are my skills doing?" or "Run selftune"

Actions:

1. selftune status for overall health summary
2. selftune last for most recent session insight
3. selftune doctor if issues detected

Result: Pass rates, trend data, and actionable recommendations.

Scenario 4: Autonomous operation

User says: "Set up cron jobs" or "Run selftune automatically"

Actions:

1. selftune cron setup to install OS-level scheduling
2. Orchestrate loop runs: ingest → grade → evolve → watch

Result: Skills improve continuously without manual intervention.

Troubleshooting

CLI not found

Error: command not found: selftune

Cause: CLI not installed or not on PATH.

Solution:

1. Run npm install -g selftune or check bin/selftune.cjs exists
2. Verify with which selftune
3. If using bun: bun link in the repo root

No sessions to grade

Error: selftune grade returns empty results.

Cause: Hooks not capturing sessions, or no sessions since last ingest.

Solution:

1. Run selftune doctor to verify hook installation
2. Run selftune ingest claude --force to re-ingest
3. Check ~/.claude/ for telemetry JSONL files

Evolution proposes no changes

Cause: Eval set too small or skill already well-tuned.

Solution:

1. Run selftune eval generate --skill <name> --max 50 for a larger eval set
2. Check selftune status — if pass rate is >90%, evolution may not be needed
3. Try selftune evolve body for deeper structural changes

Dashboard won't serve

Error: Port already in use or blank page.

Solution:

1. Try a different port: selftune dashboard --port 3142
2. Check if another process holds the port: lsof -i:3141
3. Use --no-open to start the server without opening a browser

Negative Examples

These should NOT trigger selftune — note that several are near-misses that share keywords but need different solutions:

• "Fix this React hydration bug" — general debugging, not skill improvement
• "Create a PowerPoint about Q3 results" — this is pptx skill, not selftune
• "Run my unit tests" — project tests, not skill eval tests (even though selftune has "eval unit-test", this is about *project* tests)
• "How do I use the Research skill?" — skill *usage*, not skill *improvement* (route to the Research skill itself)
• "Generate a report from this data" — content generation, not skill evolution
• "My build is failing" — project issue, not selftune health issue (even though "failing" overlaps with skill diagnostics language)
• "Evaluate this code for security issues" — "evaluate" here means code review, not session grading
• "Improve this function's performance" — code optimization, not skill optimization (even though "improve" and "performance" are selftune keywords)

The key distinction: selftune is about improving *skills themselves* (their descriptions, triggers, and execution quality). If the user is trying to accomplish a task *using* a skill, route to that skill instead.

Resource Index