[Discussion] Architectural Trade-off: Static Patterns as Probabilistic Skills vs. Deterministic Path-Based Rules

[imdcyuanzhan]

Hi @affaan-m,

First off, absolutely stellar work on this repository. It’s been an incredible resource for understanding agentic workflows in Claude Code.

I’m opening this discussion to explore an architectural design choice I noticed regarding the backend-patterns (and similar pattern-based .md files). Currently, these static coding guidelines are implemented as Custom Skills.

From an Agent engineering perspective, I'm curious about the trade-off here, specifically regarding Probabilistic Tool-Calling vs. Deterministic Context Injection:

The Core Concern

Because these patterns are packaged as "Skills", their execution relies on the LLM's semantic heuristics to trigger the tool call.
If a user writes a highly specific prompt like: "Write a backend endpoint and consult the backend-patterns skill first", it works perfectly.
However, if a user gives a broader command like: "Implement the backend API based on the attached technical design doc", there is a high probability that the LLM will bypass the skill entirely. It might just jump straight to using the Edit tool based on its pre-trained "old memory", ignoring the standardized patterns completely.

The Deterministic Alternative

Claude Code / OMC supports .claude/rules/*.md with glob-pattern routing (e.g., paths: internal/handler/**/*.go).
If these patterns were implemented as Rules instead of Skills, the context injection would be 100% deterministic. The moment the agent's Edit tool touches a handler file, the interceptor would forcefully inject the RESTful/JWT guidelines into the System Prompt, removing the LLM's "guessing game" of whether to load the context or not.

The Question

Was the decision to use Skills for static knowledge a deliberate choice for Token Economics / On-Demand Payload (i.e., avoiding context poisoning when the LLM is doing frontend work)? Or is this an area where migrating these static cheat sheets to path-based rules would be a better best practice for the community?

Would love to hear your thoughts on this architectural boundary! Thanks again for the awesome repo.

[affaan-m]

This was a deliberate trade-off, and the short version is: deterministic, path-scoped invariants belong in rules; on-demand, judgment-heavy guidance belongs in skills.

Where ECC has a rule, we want it to be something we are comfortable injecting every time a path or event matches: style floors, safety rails, harness/runtime constraints, path-specific requirements, and other low-ambiguity guidance. That is the deterministic layer.

Where ECC uses a skill, we usually want one or more of these properties instead:

• the guidance is expensive enough that always injecting it would waste context
• the task requires model judgment about whether the lane is actually relevant
• the workflow is multi-step, not just static reference text
• the surface needs handoffs to adjacent skills/rules instead of unconditional injection

So for something like backend-patterns, the skill is not meant to be a substitute for path rules. It is the deeper advisory layer. If there is a backend invariant we want enforced every time a certain file family is touched, that should live in rules. If there is a richer design/review playbook that is useful when the task actually calls for it, that should stay a skill.

In practice ECC is converging on a mixed model, not an all-skills or all-rules model:

• rules = deterministic routing for narrow, always-on constraints
• skills = on-demand workflows, richer playbooks, and token-expensive guidance

You are also right that this boundary is worth tightening. We have been steadily moving duplicated/static material out of broad skills when it really wants to be a path/event rule, and keeping skills for the parts that are genuinely procedural or judgment-heavy. So the concern is valid; the answer is not “skills everywhere,” it is a cleaner separation of concerns.

[affaan-m]

I turned this boundary into a repo doc so the answer is no longer trapped in this thread:

• docs/capability-surface-selection.md

Short version remains the same, but now it is explicit and reusable:

• rules/ for deterministic, always-on constraints
• skills/ for on-demand workflows and token-expensive playbooks
• MCP for structured interactive capabilities that justify a long-lived server surface
• plain local CLI / repo scripts for simple deterministic one-shot execution
• direct API calls inside a skill when the integration is narrow and does not yet justify MCP

That is also the repo policy going forward when external ideas come in: copy the underlying idea, then repackage it into the narrowest ECC-native surface instead of defaulting to another plugin/runtime.