agent-core

agent-core is the shared support layer for agent-driven work.

It is the canonical home for reusable agent instructions, skills, standards, templates, scripts, configs, and static reference material that are meant to be used across multiple repositories or local environments.

What agent-core is

• A central repository for cross-project agent behavior and reusable workflow assets.
• A place to keep shared guidance out of individual product repositories.
• A maintained source of truth for agent instructions, coding standards, skill definitions, templates, and lightweight automation.

What agent-core is not

• It is not a product application repository.
• It is not the place for repo-specific operational details that only make sense in one codebase.
• It is not the place for secrets, logs, generated output, or temporary scratch files.

How to use it

• Use agent-core directly when working inside this repository.
• Let other repositories reference it as a base layer for shared agent behavior.
• Keep project-specific instructions in the target repository and shared reusable guidance here.

Repository Responsibilities

Root files

• AGENTS.md Responsibility: base instruction layer for this repository and a reference point for how other repositories can compose shared guidance from agent-core.
• README.md Responsibility: explain what agent-core is, how it is organized, and what each top-level area owns.

Top-level folders

• agents/ Responsibility: reusable agent definitions and agent-family-specific instruction sets. Put here: base agent prompts, model-family behavior guides, role-specific instruction bundles. Do not put here: general coding standards, skill implementations, or repo-specific runbooks.

• configs/ Responsibility: static configuration files that support agent workflows, tooling, or local integration patterns. Put here: non-secret config files, routing metadata, publish/export config, integration mappings. Do not put here: executable scripts, large documentation, or secrets.

• docs/ Responsibility: cross-project documentation, workflow notes, conventions, and architecture-level explanations for agent-core. Put here: repository documentation, process notes, shared architecture docs, authoring guidance such as docs/DOCUMENTATION.md. Do not put here: templates, executable helpers, or one-off scratch notes.

• resources/ Responsibility: static reusable material that supports agents but is not executable. Put here: prompt snippets, reference text, examples, supporting assets, lookup material. Do not put here: scripts, mutable runtime data, or generated files.

• scripts/ Responsibility: maintenance, bootstrap, sync, packaging, and publishing automation for agent-core. Put here: shell scripts or utilities that help manage this repository and its assets. Do not put here: narrative documentation or static config that never executes.

• skills/ Responsibility: reusable skill workflows and their supporting assets. Put here: skill definitions, skill-local references, and any assets required to run those skills. Structure: public/ contains skills that are safe to share or publish. private/ contains internal-only skills that should stay out of public release paths. Do not put here: general-purpose standards or agent-family base prompts.

• standards/ Responsibility: reusable coding and authoring standards that agents should apply across repositories. Put here: language standards such as Java guidance, shared engineering rules, domain-specific coding defaults. Do not put here: repository-specific lint configs or one-off style notes tied to a single product repo.

• templates/ Responsibility: starter templates for common reusable assets in this repository. Put here: templates for AGENTS.md, skills, docs, and other repeatable content types. Do not put here: filled-in project docs or live instructions that should exist as real assets elsewhere.

Current Layout

agent-core/
  AGENTS.md
  README.md
  agents/
    README.md
  configs/
    README.md
  docs/
    DOCUMENTATION.md
    index.md
    architecture/
  resources/
    README.md
  scripts/
    README.md
  skills/
    README.md
    public/
    private/
  standards/
    java.md
  templates/
    AGENTS.template.md
    DOC.template.md
    SKILL.template.md

Placement Rules

• If the content changes how an agent behaves by default, it likely belongs in agents/, skills/, or standards/.
• If the content explains how something works, it likely belongs in docs/.
• If the content executes, it likely belongs in scripts/.
• If the content is reusable but static and non-executable, it likely belongs in resources/.
• If the content is a starting point for future files, it belongs in templates/.
• If the content is specific to one product repository, it should usually live in that repository, not in agent-core.

Authoring Principles

• Keep reusable guidance here and repo-specific guidance in the target repository.
• Prefer small, purpose-built files over large mixed-purpose documents.
• Keep executable logic separate from documentation.
• Keep public-safe and private-only assets clearly separated.
• Organize by responsibility so future agents can route content without guessing.