chore: add AI agent context structure#2967
Conversation
- AGENTS.md: org-wide entry point (cross-tool: Copilot, Claude Code, Codex) - .agents/docs/extension_guide.md: rules for extending agent context across repos - .github/docs/score_github_api.md: GitHub API reference and GraphQL snippets
umaucher
requested review from
AlexanderLanin,
MaximilianSoerenPollak and
dcalavrezo-qorix
as code owners
github-project-automation
Bot
added this to
TLC - Technical Lead Circle and S-CORE Roadmap
|
The created documentation from the pull request is available at: docu-html |
| Generic skills shared across all feature repos live in `.agents/skills/`. | ||
| Feature-repo-specific skills live in the respective repo's `.agents/skills/`. |
There was a problem hiding this comment.
we dont have feature repos 😆
You probably mean module repos.
| ## Prerequisites | ||
|
|
||
| - [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated: | ||
| ```bash | ||
| gh auth login --hostname github.com | ||
| # Token needs write:discussion scope for mutations | ||
| ``` |
There was a problem hiding this comment.
redundant in my experience. LLMs assume a pre-authenticated gh cli.
| # Token needs write:discussion scope for mutations | ||
| ``` | ||
|
|
||
| ## Useful GraphQL Snippets |
There was a problem hiding this comment.
redundant in my experience. LLMs know all these commands. May depend on used LLM.
| 4. **Personal extensions belong in `~/.agents/`** — never commit personal workflows or | ||
| knowledge-base skills to a repo. | ||
|
|
||
| ## Folder Layout & Tool Support |
There was a problem hiding this comment.
This seems good for humans, but redundant to LLMs?!
| |-------|----------|-------------|-------------| | ||
| | Repo overview, key facts | `AGENTS.md` (root) | ✅ always | ✅ | | ||
| | Generic shared skills | `score/.agents/skills/<name>/` | on-demand | ✅ | | ||
| | Feature-specific skills | `<feature>/.agents/skills/<name>/` | on-demand | ✅ | |
There was a problem hiding this comment.
Does that actually work? Loading a skill from a different location.
|
|
||
| ## Hierarchy Between Repos | ||
|
|
||
| When multiple repos are open in the same workspace (e.g. `score` + `persistency`): |
There was a problem hiding this comment.
That seems very IDE specific, as normally there are no "workspaces".
| 2. Create folder: `.agents/skills/<skill-name>/SKILL.md` | ||
| 3. Required frontmatter: | ||
| ```yaml | ||
| --- | ||
| name: skill-name # must match folder name, lowercase-hyphenated | ||
| description: 'What it does. Use when: ... triggers ...' | ||
| --- | ||
| ``` | ||
| 4. Keep `SKILL.md` under 500 lines; put detail in `./references/` subfolder | ||
| 5. Do not vendor a skill that already exists in `score/.agents/skills/` |
- AGENTS.md: rename 'feature repos' to 'module repos'; add Conventions section with gh CLI rule - extension_guide.md: remove folder ASCII tree, personal-workflow row, cross-repo skills row; drop redundant template descriptions; rename feature→module repos - score_github_api.md: remove Prerequisites section; replace verbose snippets with single annotated query explaining the non-obvious repository() workaround for org discussions
… skill scope guidance
| - **`reference_integration`** is where all feature modules are integrated and tested | ||
| end-to-end. Changes here that affect module APIs or process requirements may need to | ||
| be reflected there. | ||
| - **Documentation toolchain**: Sphinx + sphinx-needs. RST files using `.. req::`, |
There was a problem hiding this comment.
This is not we are using it, we have a own meta model, refer to doc-as-code and process description, should that not mentioned here? We have also now mixed rst and md files.
|
|
||
| ## Agent Extension (this repo) | ||
|
|
||
| Generic skills shared across all module repos live in `.agents/skills/`. |
There was a problem hiding this comment.
may add score repo here and for module as placeholder and add examples for modules?
| - [ ] `.github/docs/` — module-specific reference data, e.g. `score_github_api.md` (created when needed) | ||
| - [ ] `.github/instructions/` — Copilot-only scoped rules (created when needed) | ||
| - [ ] `.github/agents/` — Copilot-only custom agents (created when needed) | ||
| - [ ] `.github/prompts/` — Copilot-only prompts (created when needed) |
There was a problem hiding this comment.
you introduced prompts here, but never mentioned in other places where the are located like skills?
masc2023
left a comment
masc2023
left a comment
There was a problem hiding this comment.
As we know already our SDLC, based on process description, we could even give more structure for skills in general, e.g. requirements_generate, requirements-acceptance-criteria, based on project_foundation-governance
e.g.
Skill: project-governance
Purpose
Provide common governance behavior for all SDLC skills.
Use when
- A task has architectural, safety, security, quality, compliance, or release implications
- The repo or project context is partially known
- You need a reviewable, auditable output
Instructions
When invoked:
- Identify the task type:
- requirement
- architecture
- planning
- implementation
- testing
- review
- release
- operations
- Extract all explicit constraints from the prompt and any provided artifacts.
- Preserve ambiguity instead of silently resolving it.
- If the task might affect:
- functional safety
- security
- privacy
- external interfaces
- release readiness
then create a dedicated impact section.
- Produce output in a structure that a human can verify quickly.
- Never present a proposal as a final approved decision.
Standard output footer
Append:
HUMAN GATE
- What must be verified
- Who should verify it
- What should block approval
3 participants
Establishes the base structure for AI agent context across eclipse-score repos.
Changes
AGENTS.md— org-wide entry point recognized by Copilot, Claude Code, and Codex.agents/docs/extension_guide.md— rules for extending agent context (folder layout, hierarchy, how to add skills/instructions/reference docs, feature repo checklist).github/docs/score_github_api.md— GitHub API reference and reusable GraphQL snippets for discussion managementDesign decisions
.agents/is the cross-tool portable layer;.github/is Copilot-specificAGENTS.mdpoints to sources, never duplicates contentAGENTS.mdreferencing this one; see extension guide for the checklist