祝融说。

Tool, Skill, Capability -- three distinct mechanisms for capability growth. Not one, not four, but exactly three.

Pattern Layer

6.1 Three Basic Modes

An agent's capability growth is not one-dimensional. An agent can learn new knowledge, master new methods, and grow new execution abilities. But these three different forms of "growth" require three different mechanisms -- no single mechanism can cover every scenario.

The relationships and interaction flow between the three modes are illustrated below:

graph TB
    subgraph "Tool (compile-time fixed)"
        T_RF[read_file]
        T_WF[write_file]
        T_RC[run_command]
        T_GB[glob / grep]
        T_CT[commit]
        T_PL[plan / milestone]
        T_RV[review]
        T_GN[generate_*]
        T_AG[agent]
    end

    subgraph "Skill (injected knowledge)"
        SK_DIR[skills/ directory]
        SK_SCAN[Registry scan]
        SK_INJ[inject into system prompt]
        SK_USE[use_skill<br/>on-demand activation]
        SK_PR[prompts/ draft layer]
    end

    subgraph "Capability (executable artifact)"
        CA_DIR[capabilities/ directory]
        CA_MAN[manifest<br/>Environment x Lifecycle]
        CA_GEN[generate_capability<br/>write_file level]
        CA_RUN[run_capability<br/>permission check]
        CA_SHL[Shell execution]
        CA_WASM[Wasm execution]
        CA_DOCK[Docker execution]
    end

    T_RF -->|Permission::None| EXEC[tool execution]
    T_WF -->|Permission::Ask| PERM[permission check]
    T_RC -->|Permission::Ask| PERM
    T_CT -->|Permission::Ask| PERM

    SK_DIR --> SK_SCAN
    SK_SCAN --> SK_INJ
    SK_USE --> SK_INJ
    SK_PR -->|promote_prompt| SK_DIR

    CA_DIR --> CA_RUN
    CA_GEN -->|write file| CA_DIR
    CA_RUN --> PERM
    PERM -->|pass| CA_SHL
    PERM -->|pass| CA_WASM
    PERM -->|pass| CA_DOCK

    style T_RF fill:#e8f5e9
    style T_WF fill:#e8f5e9
    style T_RC fill:#e8f5e9
    style SK_DIR fill:#fff3e0
    style SK_INJ fill:#fff3e0
    style CA_DIR fill:#f3e5f5
    style CA_RUN fill:#f3e5f5
    style PERM fill:#fce4ec

Tool: fixed at compile time.

Tools are what an agent is born with -- primitives written in code, compiled into the binary, immutable at runtime. read_file, write_file, run_command, glob -- these are the atomic operations of agent capability.

The key characteristic of a Tool is unforgeability. You cannot inject a fake tool through conversation. You cannot create a new run_command by writing a .md file. The toolset in an agent's hands is deterministic, enumerable, and auditable. You can count 26 tools in the binary, each with a complete implementation and tests.

The security implication of Tools is: trust comes from compile time. The compiler and type system guarantee that a tool's implementation cannot be tampered with at runtime. You never have to worry about the agent suddenly possessing a tool it shouldn't have.

The limitation of Tools is: they do not learn. The number and functionality of tools are fixed at compile time; they cannot be added or removed at runtime. To give the agent a new atomic operation, you must change the code, compile, and deploy.

Skill: injectable knowledge.

Skills are the agent's procedural knowledge -- plain-text Markdown files stored in the skills/ directory. Each file is a methodology: code review steps, debugging workflow, work planning approach.

The key characteristic of a Skill is injectability. It is not innate knowledge -- it is read in from files. The agent loads all files from the skills/ directory via the Registry at startup, and their contents are woven into the system prompt. Add a new Skill file, and on the next turn the agent has one more methodology at its disposal.

The security implication of Skills is: trust comes from the filesystem. Skill content is plain text and contains no executable code. A file written to the skills/ directory can at most alter the agent's reasoning path; it cannot change the agent's actual operational capabilities.

The limitation of Skills is: they do not execute. A Skill can only tell the agent "how to do something"; it cannot grant the ability to "do something new." A Skill can define the steps for code review, but it cannot perform the review itself -- execution requires a Capability.

Capability: executable artifact.

Capabilities are executable code written by the agent -- stored in the capabilities/ directory, accompanied by a manifest declaring the environment and lifecycle.

The key characteristic of a Capability is executability. It is not knowledge; it is code. The agent uses generate_capability to write code and a manifest, and run_capability to execute it. The execution environment is routed to Shell, Wasm, or Docker backends according to the manifest declaration.

The security implication of Capabilities is: trust comes from the execution gate. generate_capability merely writes files (at write_file privilege level); the true gate is at run_capability (which triggers permission checking). Writing is cheap, execution is expensive -- this principle runs throughout the entire tripartite architecture.

The limitation of Capabilities is: they require an environment. A Capability's execution depends on whether its declared environment is available. If Docker is unavailable, a Capability that declares Docker cannot execute.

6.2 Why Exactly Three

The tripartite division is not an architect's aesthetic preference -- it is a natural classification born from three distinct security boundaries.

Derived from security boundaries:

• Compile-time security requires an unforgeable primitive layer → Tool
• Injection security requires a non-executing knowledge layer → Skill
• Execution security requires an execution layer with a permission gate → Capability

Each layer answers a different question of "how is trust established." Tool trust comes from the compiler and type system. Skill trust comes from the filesystem's read-only nature (files do not spontaneously turn into code). Capability trust comes from the execution gate (writing a file does not trigger permission checks; executing a file does).

Fewer than three:

• Tools only: the agent cannot learn new knowledge. Every time it encounters the same problem, it must reason from scratch. There is no place to store "this project's coding preferences" or "this team's preferred approach."
• Tools + Skills only: the agent can learn and reason, but learned knowledge cannot become executable capability. If the agent discovers that "deployment always requires these steps," it cannot write a script and reuse it.

More than three:

In theory, a fourth category could be added -- for instance, "configurable Tools" (plugins loaded at runtime), "dynamic Skills" (knowledge loaded remotely from a network), and so on. But each additional category introduces a judgment boundary of "which category does this new capability belong to." Three is precisely the upper limit of "what one person can mentally track across all categories." When a new capability growth requirement arises, the tripartite framework can nearly always accommodate it:

• Need a new atomic operation → add a Tool (requires compilation)
• Need a new decision method → write a Skill (requires injection)
• Need a new executable capability → generate a Capability (requires a gate)

If it does not fall into any of the three -- then perhaps this capability should not be managed by the agent itself.

6.3 The Draft Layer Beyond the Three

Beyond the three categories, there is a "quasi-category": the Prompt draft layer.

The prompts/ directory holds Skills in draft state. It exists because there needs to be an intermediate state between "knowledge temporarily generated by the agent" and "knowledge becoming a formal Skill."

Maturity model:

Message (ephemeral) → Prompt draft (single use, prompts/) → Skill (formalized, skills/) → Resident (injected into system prompt)

• Message: knowledge generated by the agent mid-conversation, used once, not persisted
• Prompt draft: a draft written to prompts/ by the agent using generate_prompt. Activated on demand once via use_skill; not automatically injected at startup
• Skill: promoted from draft to formal Skill via promote_prompt. Moved from prompts/ to skills/, automatically injected at startup
• Resident (injected into system prompt): a Skill marked as "high-frequency usage," permanently present in the system prompt

Each promotion step has a clear tool operation. generate_prompt → promote_prompt → automatic injection. There is no implicit upgrade where "a casual remark becomes permanent behavior."

The draft layer is not a fourth category -- it is the "immature state" of a Skill. Drafts and formal Skills share the same tool path (use_skill); the difference lies in loading timing (on-demand vs. automatic).

Case Layer

6.4 Registry Scanning and Activation Flow

The Registry is the filesystem interface of the tripartite architecture. It is responsible for scanning, indexing, and injecting the three types of capabilities.

struct Registry {
    skills: HashMap<Name, SkillEntry>,      // formal Skills under skills/
    prompts: HashMap<Name, PromptEntry>,    // drafts under prompts/
    capabilities: HashMap<Name, CapabilityEntry>, // Capabilities under capabilities/
}

enum RegistrySource {
    Skill { path: PathBuf, promoted: bool },
    Prompt { path: PathBuf, created_at: Instant },
    Capability { path: PathBuf, manifest: Manifest },
}

The Registry startup flow:

1. Scan the skills/ directory, collect all .md files → skills HashMap
2. Scan the prompts/ directory, collect all .md files → prompts HashMap
3. Scan the capabilities/ directory, collect manifest files from each subdirectory → capabilities HashMap
4. Build the resident registry table: skills content → summary list → inject into system prompt
5. Prompts and capabilities content are not injected into the system prompt; they are loaded only when the agent calls them on demand

The /reload command re-executes steps 1-5 without restarting the daemon.

6.5 Directory → Registry → System Prompt Injection Path

The path from a skills/ file into the system prompt:

skills/security-review.md
    ↓
Registry scans → reads file content
    ↓
Build resident registry table:
  - name: security-review
  - source: Skill { path: skills/security-review.md, promoted: true }
  - content: "When reviewing code, follow this order: 1) Input validation 2) ..."
    ↓
Inject at the tail of the system prompt:
  "You have the following Skills available:\nsecurity-review: When reviewing code, follow this order: ..."
    ↓
The agent can reference it directly in a turn: "follow the security-review steps"

The capabilities/ path differs -- its content is not injected into the system prompt; only an availability hint is injected:

capabilities/daily-report/
├── manifest.yaml
└── main.sh
    ↓
Registry scans → reads manifest
    ↓
Build available capabilities list (names only, no content):
  "You have the following Capabilities available: daily-report (Shell/OnDemand)"
    ↓
The agent reads the manifest and code only when it calls run_capability daily-report

This "names only, not content" design avoids Capability code consuming system prompt token budget.

6.6 Complete Self-Evolution Loop Example

Below is the complete loop of an agent progressing from problem discovery to knowledge crystallization as a Skill:

Step 1: The agent identifies a recurring pattern during code review
  → "Every time I review Python code, I need to check import order"

Step 2: The agent writes a draft using generate_prompt
  → generate_prompt(name: "python-import-review", content: ...)
  → File written to prompts/python-import-review.md

Step 3: The agent tries the draft in the next review
  → use_skill("python-import-review")
  → Draft content injected into the current context

Step 4: After several trials, the agent confirms the Skill is worth formalizing
  → promote_prompt("python-import-review")
  → File moved from prompts/ to skills/
  → Registry updated, automatically loaded on next startup

Step 5: The agent automatically uses this Skill in subsequent reviews
  → skills/python-import-review.md is in the system prompt
  → Every time the agent reviews Python code, it checks import order

The key to this loop is the interval between Step 3 and Step 4. A draft is not automatically promoted upon creation. The agent needs to validate the Skill's value through actual use before explicitly deciding to promote it. Promotion is an independent agent action -- not automatic, not implicit.

If a generated Skill is of poor quality or too narrow in scope, it can be abandoned at the draft stage -- files in prompts/ can be deleted without affecting the formal knowledge base in skills/.

ADR Deep Dive

Motivation for the Prompt Draft Layer (ADR 0025)

ADR 0025 records a problem exposed in practice: the quality of agent-generated Skills was unstable.

Before the draft layer existed, the agent used generate_skill to write files directly into skills/. The problem was this: the first version a Skill generated by the agent almost always needed revisions. Terminology was inconsistent, step ordering was unreasonable, and acceptance criteria were vague.

The initial approach was to have the agent regenerate repeatedly -- generate, review, identify issues, modify, regenerate. But during modification, the agent could introduce new problems, and the boundary between "modifying a Skill" and "using a Skill" became blurred in the agent's context.

The solution was to introduce an intermediate state: the prompts/ draft directory. The agent's first-generation artifact enters prompts/ and only enters skills/ after explicit promotion via promote_prompt. The core of this change is not the addition of a directory -- it is the insertion of a promotion gate between "write" and "use."

The significance of the promotion gate is that it is neither human approval nor automatic passage. The agent performs the creation action (generate_prompt), the promotion decision (promote_prompt), and uses trial validation in between (use_skill loading from draft). Each independent operation is the agent's autonomous decision -- yet every step can be audited by the user.

Another motivation recorded in this ADR is preventing skills/ from accumulating unvalidated Skills. If every rough draft generated by the agent went directly into the formal knowledge base, skills/ would quickly balloon to an unmanageable size. The draft layer serves as a "buffer pool" -- quality content gets promoted, low-quality content gets cleaned up over time.

The next chapter delves into the design of the Skill system -- procedural knowledge injection timing, provenance mechanisms, and the complete implementation of draft promotion.