Artifact Types¶

Agentic Beacon organizes warehouse artifacts along two independent axes — project scope and tool specificity — producing four types. Understanding this matrix explains why each command behaves the way it does.

The Matrix¶

	Tool-agnostic	Tool-specific
Project-scoped	📄 Contexts · 🧠 Knowledge	⚡ Skills · 🤖 Agents
Global	—	—

The bottom-left cell (global + tool-agnostic) is intentionally empty: a globally shared, tool-agnostic artifact would have no natural installation location, which is not a pattern Agentic Beacon supports.

Not an Artifact: Agent Config Files¶

Beacon also touches one set of files that are not artifacts: the agent config files (opencode.json, CLAUDE.md). These hold no shared content and are not synced from the warehouse — they are per-project files that the AI tool reads at session start.

Beacon manages them via agent config wiring: it bootstraps them on first setup and keeps the synced context references inside them current on every sync — idempotently and without touching user-authored entries. This is the "wire" step of the sync flow; see the Adopting Artifacts guide for per-tool detail.

Agent config files are listed here for completeness, not because they fit the matrix — they sit underneath it as the runtime surface that artifacts get wired into.

📄 Contexts — Project-scoped, Tool-agnostic¶

Contexts are boot instruction files: coding standards, architectural constraints, team conventions. The agent reads them at session start.

Project-scoped because the standards relevant to a data pipeline differ from those in a mobile app. Each project controls which contexts it loads via beacon.yaml.

Tool-agnostic because the content is plain markdown. The wiring mechanism adapts to the tool (opencode.json vs. CLAUDE.md), but the file itself is identical.

Declared in beacon.yaml:

contexts:
  - contexts/global.md
  - contexts/teams/backend/AGENTS.md

Where they live after sync:

.agentic-beacon/artifacts/contexts/global.md  →  symlink to warehouse

How they're wired: - Claude Code: appended as @.agentic-beacon/artifacts/contexts/global.md to CLAUDE.md - OpenCode: added as a file reference in opencode.json

🧠 Knowledge — Project-scoped, Tool-agnostic¶

Knowledge artifacts are atomic reference documents: decisions and their rationale, lessons learned, coding patterns, framework guides.

Project-scoped because each project's contexts reference different knowledge files.

Tool-agnostic — plain markdown, referenced by path from contexts and skills.

NOT declared in beacon.yaml. Knowledge files are auto-derived from markdown links in adopted contexts and skills. When a context says:

See the [Python type hints guide](knowledge/python/type-hints.md).

The dependency resolver finds knowledge/python/type-hints.md and syncs it automatically. No manual configuration needed.

Where they live after sync:

.agentic-beacon/artifacts/knowledge/decisions/coding-standards.md  →  symlink to warehouse

⚡ Skills — Project-scoped, Tool-specific¶

Skills are reusable procedures available as slash commands during a session. To function they must be physically present in a tool's live skill directory.

Project-scoped because a skill often depends on the project's toolchain (e.g., a run-migrations skill assumes the project has a migrations setup).

Tool-specific because each tool has its own installation path:

Tool	Skill location	Command location
Claude Code	`.claude/skills/<name>/`	`.claude/commands/<name>.md`
OpenCode	`.opencode/skills/<name>/`	`.opencode/command/<name>.md`

Declared in beacon.yaml as directory-level entries:

skills:
  - skills/code-review/
  - skills/generate-tests/

Must include frontmatter requires: in SKILL.md:

---
requires:
  contexts:
    - global.md
    - teams/backend/AGENTS.md
---

Missing frontmatter causes sync to fail with a hard error — all required contexts must be available.

🤖 Agents — Project-scoped, Tool-specific¶

Agent definitions are sub-agent profiles — specialized agents that can be invoked from any project (code reviewer, test writer, PR description generator, etc.).

Project-scoped because agents are declared per-project in beacon.yaml.artifacts.agents.

Tool-specific because each tool has its own project-local agent directory. Declared agents are symlinked into:

Tool	Project-local agent directory
Claude Code	`.claude/agents/` (inside the project root)
OpenCode	`.opencode/agents/` (inside the project root)

Agent symlinks are project-scoped, so each project controls which agents are available without sharing state across projects on the same machine.