简体中文

Documentation Entry for Agents

This directory is the decision entry point of Skill Family Foundation for agents (Agents). Human readers enter from the root README.md; agents, within a limited context, read here first, then jump to the specific capability by intent, avoiding reading all the source code end-to-end.

Foundation does not own business semantics. It provides only three things: machine contracts (Contracts), the thin Node mechanism runtime (Harness), the four engineering-phase commands (Engineering Kit), and the horizontally-declared-difference Profile. Domain state machines, model orchestration, remote publish writes, and audit semantics all stay with the caller or other projects.

Reading Order

Agents consume the following in order, without needing to read from start to finish:

1. ../../agents/capability-catalog.json — the language-neutral machine-fact catalog of stable and candidate capabilities; the starting point for judging "does this requirement belong to Foundation, in which layer, and with which entry point."
2. architecture-routing.md — the decision table and decision tree from architecture intent to layer/capability/entry-point/external-project.
3. ../../agents/capability-catalog.en.json — English intent, use conditions, inputs, outputs, failure semantics, caller ownership, and external routing for exactly the same capability IDs.
4. ../../agents/capability-catalog.schema.json — the closed structural contract for the core catalog and locale overlays.
5. The root README.md's Agent Quick Reference — routing only, no API duplication.
6. The three packages' README Agent Quick References — down to package-level capabilities and failure boundaries.
7. ../reference/failure-and-side-effect-matrix.md — read/write/spawn/Git/network/residual-state/error-code for each public entry point.
8. ../reference/api/README.md — the English API route across the three packages, including key capabilities, failure rules, evidence paths, and caller-owned semantics.

Fact priority: this documentation consumes only the machine source of truth (package.json, src/index.mjs, CLI, registry.json, profile descriptor). Versions, commands, package counts, and support states are recomputed from the source of truth, never copied from memory or old docs.

Catalog Contract

Files under docs/agents/ assume different responsibilities and do not duplicate each other:

File	Role	Who should change it
../../agents/capability-catalog.json	Language-neutral machine-readable capability facts; the documentation layer's sole fact surface	Change when capabilities change, validated by capability-catalog-check.mjs
../../agents/capability-catalog.en.json	English explanation overlay for every core capability ID	Change when the English intent or behavior explanation changes
../../agents/capability-catalog.zh-CN.json	Simplified Chinese explanation overlay for every core capability ID	Change when the Chinese intent or behavior explanation changes
../../agents/capability-catalog.schema.json	Closed catalog and overlay structural contract	Change only when structure changes
architecture-routing.md	Intent → layer/capability/entry-point/external-project decisions	Change when routing adjudication changes
README.md (this file)	Agent total entry point and reading order	Change when entry-point structure changes
../reference/api/README.md and the three Chinese package detail pages	Human-readable routing and signature-level expansion of catalog capabilities	Change when real exports change, and sync with capability-catalog-check.mjs

The capability catalog is not a new public object of Contracts, nor a fourth registry class. It is only the documentation layer's machine facts, avoiding the README becoming a second drifting handwritten authority.

Architecture Design Method

When an agent handles a Foundation-related requirement, it proceeds in the following four steps:

1. Decide ownership first. Does this requirement contain domain semantics, a business state machine, or an audit oracle? If so, keep it with the consumer, connecting only business-neutral mechanisms to Foundation.
2. Then decide the layer. Structure/protocol/stable error code/object Schema → Contracts; cross-skill-family reusable Node mechanism → Harness; scaffold/adopt/projection/check or concrete Profile injection → Kit/Profile.
3. Check the catalog to determine the entry point. Find the capability by layer in the core catalog, then read the matching intent, sideEffects, failureSemantics, ownedByCaller, and routeElsewhere in the English overlay.
4. Verify evidence before concluding. Each catalog capability carries sourceRefs and positiveTestRefs/negativeTestRefs; before changing a judgment, return to these sources of truth to confirm, rather than inferring from the catalog's prose.

The hard rule of routing boundaries: Foundation does not own remote writes (→ release-skill), does not own tasks/retries/rework (→ loop-agent), does not own artifact relationships and context (→ artifact-graph), does not own domain-audit semantics (→ independent audit consumer). See the routing table in architecture-routing.md for details.

For a candidate capability, entrypoints always lists the canonical identity. A simultaneous legacyEntrypoints field marks pre-0.10.0 debt that consumers migrate once. Stable promotion after that migration does not change the contract identity, although consumers must update their exact pins to obtain the newly published stable promise. Candidate capabilities introduced from 0.10.0 onward must not encode maturity in the capability ID, entrypoint, Schema $id, or operation.

Relationship with Mechanical Gates

Two check scripts guard the catalog and README against drift:

• scripts/docs/capability-catalog-check.mjs validates structure, unique IDs, existence of source/test references, unsupported boundaries, and that the Kit's four commands are not expanded.
• scripts/docs/agent-section-check.mjs validates the fixed Agent Quick Reference sections of the root README and the three packages' READMEs, the required subheadings, and capability-ID links.

Neither only reports shape and does not auto-edit; warnings require returning to the source of truth and human judgment.