Skip to content

Knowledge Way

Source: hooks/ways/meta/knowledge/knowledge.md

Frontmatter
Field Value
description Overview of the ways system — how ways, skills, and hooks relate, domain organization, matching modes
vocabulary ways way knowledge guidance context inject hook trigger matching semantic vocabulary domain
pattern (^| )ways?( |$)|context.?inject
refire 0.15
scope agent, subagent

Ways vs Skills

Skills = semantically-discovered (Claude decides based on intent) Ways = triggered (patterns, commands, file edits, or state conditions)

Use Skills for Use Ways for
Semantic discovery ("explain code") Tool-triggered (git commit → format reminder)
Tool restrictions (allowed-tools) File-triggered (edit .env → config guidance)
Multi-file reference docs Refire-gated, re-injects after its refire: fraction
Dynamic context (macro queries API)

They complement: Skills can't detect tool execution. Ways support both regex and semantic matching.

How Ways Work

Ways are contextual guidance that discloses when triggered by: - Keywords in user prompts (UserPromptSubmit) - Tool use - commands, file paths (PreToolUse) - State conditions - context threshold, file existence (UserPromptSubmit)

State Machine

(not_shown)-[:TRIGGER {keyword|command|file|state|embed}]->(shown)  // output + stamp epoch
(shown)-[:TRIGGER, suppressed]->(shown)                             // hold — re-disclosure threshold not met
(shown)-[:TRIGGER, threshold met]->(shown)                          // re-inject to course-correct

Disclosure isn't once-and-done. Each agent keeps its own record of when a way fired (main at the session root, each subagent under agents/<id>/); after a fire the way waits out its refire: fraction of the context window, then becomes eligible to re-inject when it matches again. Re-disclosure course-corrects drift over long sessions — it isn't verbatim repetition. Multiple ways can fire per prompt. Project-local wins over global for same name.

Locations

Three way roots (ADR-143) — don't confuse reading one with authoring in it:

  • Framework ways (read-only projection): ~/.claude/hooks/ways/{domain}/{wayname}/{wayname}.md — a symlink into the app source at $XDG_DATA_HOME/agent-ways. Readable here, but don't author durably in it: ways update pulls the app dir with an autostash, so edits there conflict with upstream. Change these in a dev checkout and reproject (see docs/development.md).
  • Your own ways (user scope, survives updates): $XDG_CONFIG_HOME/agent-ways/ways/{domain}/{wayname}/{wayname}.md
  • Project ways: $PROJECT/.claude/ways/{domain}/{wayname}/{wayname}.md — override global ways at the same path
  • Disable domains: $XDG_CONFIG_HOME/agent-ways/config.yaml → disabled_domains: [domain]
  • Ways can nest: {domain}/{parent}/{child}/{child}.md for progressive disclosure
  • When a parent way fires, its in-domain children become eligible on weaker signal: the child's semantic bar drops from τ_s to (τ_s × parent_threshold_multiplier).max(parent_boost_floor) = max(0.5×0.8, 0.30) = 0.40 by default (multiplier boosts, floor caps) — domain context is established
  • Tree disclosure metrics are tracked per agent (parent, depth, epoch distance, sibling coverage)
  • Think strategies are multi-turn ways that steer reasoning across several turns (auto-detected, opt-out)

See Also

  • knowledge/authoring(meta) — how to write and tune ways
  • knowledge/optimization(meta) — vocabulary health and scoring calibration
  • skills(meta) — skills complement ways with tool-specific bindings