69 lines
3 KiB
Markdown
69 lines
3 KiB
Markdown
# .agents/
|
|
|
|
Agent configuration for this repository. The `.agents/` layout tracks the
|
|
[agents folder convention](https://github.com/agentsfolder/spec), while skills
|
|
inside it follow the [open Agent Skills format](https://agentskills.io/specification):
|
|
each skill is a directory with `SKILL.md` frontmatter and Markdown
|
|
instructions.
|
|
|
|
SF treats this as `sf-agents-overlay/v1` until the external `.agents` spec
|
|
settles. The stable contract is:
|
|
|
|
- `.agents/manifest.yaml` is the repo-owned machine index.
|
|
- `.agents/prompts/`, `.agents/policies/`, `.agents/modes/`, `.agents/scopes/`,
|
|
`.agents/profiles/`, and `.agents/adapters/` are optional project override
|
|
inputs.
|
|
- `.agents/skills/<name>/SKILL.md` is the canonical skill payload.
|
|
- `.agents/skills/<name>/skill.yaml` may exist as generated or adapter metadata,
|
|
but it is not the instruction source.
|
|
- `.agents/state/state.yaml` is local-only and ignored.
|
|
- `.sf/` remains SF runtime state; structured SF state is DB-first.
|
|
|
|
This folder is the **override and extension layer only**. SF's built-in
|
|
defaults (modes, skills, policies) apply automatically. Files here exist
|
|
only when the project needs to override or add something.
|
|
|
|
This mirrors Copilot-style project customization: repository-owned agent
|
|
instructions and optional overrides live in the repo, while product-shipped
|
|
defaults live outside the repo overlay. For SF, bundled user-visible skills are
|
|
sourced from `src/resources/skills/`; hidden workflow pattern skills are sourced
|
|
from `src/resources/workflow-skills/`; bundled default prompts and policies are
|
|
sourced from `src/resources/agent-overlays/singularity-forge/`. `.agents/`
|
|
only adds project-specific overrides.
|
|
|
|
## Structure
|
|
|
|
```
|
|
.agents/
|
|
AGENTS.md ← this file
|
|
manifest.yaml ← SF overlay schema; no enabled overrides by default
|
|
prompts/
|
|
.gitkeep ← project prompt overrides only
|
|
snippets/ ← project prompt fragments only
|
|
modes/ ← project mode OVERRIDES only (empty — SF built-ins apply)
|
|
policies/
|
|
.gitkeep ← project policy overrides only
|
|
skills/ ← optional project user skills + built-in overrides (empty by default)
|
|
scopes/ ← path-based config overrides (empty)
|
|
profiles/ ← named overlays e.g. "ci", "dev" (empty)
|
|
adapters/ ← optional projection targets (absent until needed)
|
|
schemas/ ← generated JSON schemas (not committed)
|
|
state/
|
|
.gitignore ← excludes state.yaml (per-developer convenience, never committed)
|
|
```
|
|
|
|
## Override pattern
|
|
|
|
To override a built-in mode or skill, add a file with the **same name**:
|
|
|
|
```
|
|
# Override a product workflow pattern for this repo
|
|
.agents/skills/sf-repo-orientation/SKILL.md
|
|
|
|
# Override built-in build mode
|
|
.agents/modes/build.md
|
|
```
|
|
|
|
Built-in defaults (ask, build, autonomous modes; default-safe policy; bundled
|
|
prompts; bundled user skills; hidden workflow pattern skills) are provided by SF from
|
|
`src/resources/` and do not need to be listed here.
|