Scientific Agent Skills
Arquitectura de Scientific Agent Skills: estándares, contratos y evidencia
Traza SKILL.md, plugin.json, adaptadores de bases de datos y revisión humana en una arquitectura portable.
Qué aprenderás
- Trace discovery, contract, adapter, and evidence layers
- Classify failures at the correct boundary
- Design a governed, portable research-agent deployment
Antes de empezar
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Conclusiones clave
- Discovery, skill contracts, capability adapters, and evidence review are separate layers.
- Host-specific paths and metadata make portability a claim to verify, not assume.
- Model output becomes useful research only when source identifiers and human accountability travel with it.
The architecture in one sentence
Scientific Agent Skills separa descubrimiento y empaquetado, contrato SKILL.md, herramientas y bases de datos, y registro de evidencia con revisión cualificada. Las rutas y metadatos dependen del host, así que hay que fijar cliente y versión.
That separation is valuable because it makes a workflow inspectable before execution. It also means portability is not magic: each host decides where it searches, which metadata fields it honors, and how it exposes tools or credentials. Architecture claims should therefore name the host and revision rather than treating every adapter as equivalent.
Four layers to trace
First is discovery and packaging: `skills/` folders, YAML frontmatter, `plugin.json`, and host-specific install paths. Second is the skill contract: a `SKILL.md` describes purpose, inputs, steps, examples, and limits. Third is capability access: Python packages, database APIs, MCP servers, or integrations that a workflow invokes. Fourth is evidence and review: identifiers, citations, artifacts, uncertainty, and the qualified person who approves a conclusion.
The database layer is intentionally heterogeneous. The README groups unified database lookup with dedicated connectors and package skills, so a single natural-language question can cross several APIs. Preserve the boundary between orchestration and source interpretation: a connector can return a record, but it cannot decide whether that record supports a clinical or scientific claim.
Failure paths are part of the design
A missing `SKILL.md` or plugin entry is a discovery failure; a package import error is an environment failure; a rate limit or expired token is a provider failure; and an answer with no primary citation is an evidence failure. Handle these as different states in logs and user messaging. Do not silently fall back to an unreviewed API or invent a result when a capability is unavailable.
For multi-step research, pass a run context containing the skill revision, input hash, source identifiers, and timestamps. Keep transient credentials out of that context, and give each external call a bounded timeout and retry policy. A deterministic run record helps an operator reproduce a problem without replaying sensitive material.
Design implications for adopters
The portable standard lowers integration cost, while the collection's breadth raises governance cost. Teams should publish an allow-list of skills, network domains, packages, and output destinations; assign owners; and test host upgrades in a canary workspace. Use the repository's validation and security workflows as structural gates, then add domain-specific tests for the skills that matter to your lab.
The architecture supports rich research assistance, not autonomous authority. Keep human review at the edge where evidence becomes a recommendation, diagnosis, regulatory artifact, or release decision. That is the point where provenance, uncertainty, and professional accountability must be visible to the reader.
Cómo elegir
| Criterio | Opción A | Opción B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Pasos de implementación
- 1
Map the host discovery path and pin the collection revision.
- 2
Read one SKILL.md and list its packages, APIs, MCP servers, and file writes.
- 3
Define run-context fields for revisions, identifiers, timestamps, and citations.
- 4
Canary host upgrades and require qualified review at the decision boundary.
Ejemplo para copiar
discovery -> SKILL.md contract -> tools/databases -> evidence record -> qualified review
run_id: 2026-08-31-demo
skill_revision: <commit>
source_ids: [<primary identifiers>]
review_status: draftPreguntas frecuentes
Is plugin.json the same as a model or API gateway?
No. It packages discoverable skills for compatible clients; models, tools, credentials, and external data providers remain separate runtime dependencies.
Can one host guarantee identical behavior to another?
No. Discovery paths, metadata support, permissions, and tool adapters vary. Test the exact host and revision you plan to operate.
Fuentes
- Scientific Agent Skills README (captured 2026-08-31)Fuente verificada 2026-08-31
- Scientific Agent Skills repositoryFuente verificada 2026-08-31