Capabilities without a Giant Prompt
CloddsBot’s skill system answers a practical problem: how can one agent work across many kinds of markets and services without loading every possible action into every model request? This chapter distinguishes the repository’s prompt instructions, executable handlers, and model-visible tool definitions, then follows the gates and discovery rules that connect them. The distinction matters because a capability can be documented, loadable, and visible to the model without being ready—or safe—for a particular user or environment.
Instructions, code, and availability are different things
A SKILL.md file is primarily an instruction surface. It can describe what a capability does, define its commands, supply metadata, and tell the agent how to use other tools. It is not, by itself, the code that places an order or queries a chain. A TypeScript handler is the executable surface. It implements a handle function or equivalent behavior and performs the operation when the application dispatches it. CloddsBot can use both for one capability: the Markdown explains the behavior to the model, while the handler supplies the actual runtime action.
That separation protects against a common conceptual error. Documentation can say that a system supports a futures exchange; the handler must still import, authenticate, validate, and call the exchange client. Conversely, code can exist while the model lacks the instructions or tool schema needed to select it. The useful unit is not “the skill” as a single object but the relationship among explanation, executable behavior, and invocation.
The loader treats a skill as a conditional capability. Environment gates require particular variables, such as an API key or private key. Binary gates require an installed command. Operating-system gates keep a capability on the platforms where it is expected to work. Configuration gates require a setting to be present and truthy. If a gate fails, the skill can remain visible with an unavailable status rather than pretending that its missing dependency has been solved.
This is particularly important in a trading terminal because readiness is contextual. A market-data skill may work with public endpoints while its order-placement companion needs credentials. A Solana capability may need a wallet and a chain connection. A local development tool may require Docker or a platform-specific binary. A user who sees a command in a help screen still needs to know whether the required environment exists and whether the capability is read-only, simulated, or able to create an external side effect.
CloddsBot also supports more than one place for skills. Workspace and user-managed locations can override bundled capabilities, and the loader can resolve a skill’s base directory, add bundled binaries to its path, and apply environment overrides for a run. This makes the system adaptable: an operator can add a project-specific workflow without editing the core application. It also changes the trust model. Higher-priority content can alter what the agent is told to do, which executable handler is selected, or which binary is available. Extensibility therefore needs review and access control; it is not automatically benign because the file is called a skill.
The TypeScript executor addresses dependency failure with lazy dynamic imports. Rather than importing every handler at startup, it loads the manifest on first use and attempts each handler independently. The use of Promise.allSettled() means one broken or missing SDK can be recorded as a failed skill while other handlers remain available. This is a sensible resilience boundary for a repository that spans many heavy and sometimes platform-specific libraries. It also has a precise limit: isolation keeps one failure from taking down the whole capability registry, but it does not make the failed capability functional.
There are two ways for a command to reach behavior. A normal skill command can be resolved to a handler and run through the executor. A skill may instead declare direct command dispatch, which sends a command straight to a designated tool and bypasses the LLM. Direct dispatch is useful when interpretation adds no value or creates unnecessary ambiguity. It can make a well-defined operation more predictable and cheaper. But it also removes the model’s opportunity to ask a clarifying question or explain an unsafe assumption. The application must ensure that the command parser, target tool, permissions, and arguments provide the needed control.
The result is a layered availability model:
- The skill description may be present for the model.
- The gate may say whether its prerequisites are met.
- The handler may or may not load successfully.
- The tool registry may or may not expose the definition in the current turn.
- The downstream service may still reject the request because credentials, limits, or market state are wrong.
Only the last step reaches the external system, and each earlier step can fail for a different reason. Treating “listed” as “ready” would hide precisely the distinctions a control plane is meant to preserve.
The separation also gives CloddsBot a useful way to make startup less fragile. Prompt files can be parsed and marked according to their gates, while executable handlers are loaded lazily and independently. A missing SDK for one venue need not prevent an unrelated market-data skill from being used. When a dependency later becomes available, a reload can refresh the capability surface without requiring the operator to redesign the agent. The cost is that readiness becomes dynamic: the answer to “can CloddsBot do this?” depends on the current process, environment, configuration, and external service, not just on what exists in the repository.
A concrete example is the difference between reading and acting. A skill may teach the model how to inspect a market’s current price and another may teach it how to place an order. The first can often work with public data; the second may require a wallet, signed credentials, a configured execution service, and a passing risk gate. They can be related in the user experience, but they should not share an assumed trust level. The system’s design is strongest when a successful lookup remains a lookup until the user and the action path provide the additional conditions required for an external side effect.
The same principle applies to custom skills. The loader’s support for workspace and user-managed locations is a product advantage because it lets an operator adapt CloddsBot to local workflows. It is also a supply-chain-like boundary inside the instance: a new Markdown instruction, binary, or environment override can change what the agent sees and what a handler can reach. Review, whitelisting, dependency gates, and the ability to disable a skill are therefore part of capability management. A modular extension point is not a security verdict.
Discovery controls what the model can reach
CloddsBot’s agent manager builds a registry from the available tool definitions and attaches metadata such as platform, category, and tags. A core set remains available for common work such as market discovery, portfolio questions, alerts, credential setup, and tool search. Specialized definitions can be preloaded when the user’s message contains recognizable platform or intent hints. If the message mentions a platform and a trading action, the registry can prefer tools matching both rather than exposing every tool associated with either word.
When hints are insufficient, the model can call tool_search. The meta-tool searches by platform, category, or text and returns definitions that can be used in follow-up calls. The newly discovered tools join the active set for that request, subject to a global cap. This is a form of capability negotiation inside the agent turn: the model first asks what it can use, then receives a constrained description of the available actions.
The registry is not merely a performance optimization. Every tool definition consumes model context and gives the model another possible action. Sending a huge undifferentiated set increases prompt cost and makes selection harder; sending too little can cause the model to miss a relevant capability. CloddsBot’s core-plus-discovery design attempts to balance those pressures. It keeps familiar read-oriented actions close at hand, uses the message to narrow likely domains, and retains a search path for less common work.
The narrowing logic is deliberately imperfect. It relies on platform names, action words, categories, and recent conversation hints. A user can use an abbreviation or an unexpected description, and the registry may preload the wrong group or require a second search. That is a usability trade-off rather than a proof of semantic understanding. The model still has to choose the correct tool and provide valid arguments, and the handler still has to enforce the actual business and safety rules.
The tool registry also demonstrates why metadata should not be confused with capability. It can infer that a definition is associated with a platform or that its description sounds like trading, portfolio, data, or infrastructure work. Those labels improve retrieval. They do not validate the market, authenticate the user, prove that a route is liquid, or authorize a private-key operation. Metadata helps decide what to show; executable code and downstream gates decide what can happen.
The repository’s counts make the same point about evidence. Its current skills documentation describes 121 prompt skills and 118 handlers, while the README, package metadata, and older architecture prose use different totals and the internal tool comments describe a larger surface than the public summary. The safest interpretation is not to select one number as the permanent truth. The stable fact is architectural: CloddsBot has a substantial, changing capability surface with separate prompt and execution layers. Exact totals belong to a particular revision and document.
This arrangement creates useful failure behavior. If an optional handler cannot import, the agent can report that the capability is unavailable while other functions continue. If a gate lacks an API key, the skill can explain what is missing rather than issue a malformed request. If a user asks for an unfamiliar action, tool_search can discover a definition without sending every specialized schema on every turn. These behaviors make the system easier to operate than a monolithic startup, where one missing dependency could prevent even unrelated market queries.
They also create new review questions. A user-managed skill can change the instructions injected into the model. A direct-dispatch command can bypass model-level clarification. A handler can be available while an external API is degraded. A tool search result can be relevant by name but wrong for the exact market or account. The security controls documented elsewhere—input checks, allowlists, sandbox restrictions, and audit logging—remain necessary because capability discovery expands the routes from language to code.
For an operator, the right test is not whether the registry can find a promising name. It is whether the whole capability path can explain its inputs, outputs, side effects, and stopping conditions. Before enabling a trading-related extension, one should be able to identify the data it reads, the credentials it uses, the account or wallet it can affect, the limits applied before execution, and the record produced afterward. The skill description can make that path easier to understand, but only the handler and its downstream services determine the actual behavior.
This is also why a capability count has limited architectural value. Adding another handler may increase reach while also increasing dependency load, prompt-selection ambiguity, and the number of states that need testing. A smaller, well-gated set of tools can be more trustworthy than a larger set whose readiness is unclear. CloddsBot’s dynamic registry is an attempt to keep the model’s immediate choice set manageable; it should not be read as a substitute for capability review.
The skill system thus solves one boundary problem while exposing another. It prevents capability breadth from becoming a permanent prompt burden and prevents one broken integration from taking down the whole application. It does not solve the meaning of the data returned by those capabilities. Before the agent can use a specialized market tool responsibly, the next layer must establish what its price, orderbook, and freshness actually represent.