chore: add AI agent context structure#2967
Open
umaucher wants to merge 3 commits into
Open
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 |
Comment on lines
+32
to
+33
| Generic skills shared across all feature repos live in `.agents/skills/`. | ||
| Feature-repo-specific skills live in the respective repo's `.agents/skills/`. |
Member
There was a problem hiding this comment.
we dont have feature repos 😆
You probably mean module repos.
Comment on lines
+15
to
+21
| ## 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 | ||
| ``` |
Member
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 |
Member
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 |
Member
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 | ✅ | |
Member
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`): |
Member
There was a problem hiding this comment.
That seems very IDE specific, as normally there are no "workspaces".
Comment on lines
+64
to
+73
| 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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