| name | knowledge-sync |
| description | Keeps all AI-agent documentation in sync with the codebase: root AGENTS.md, per-project AGENTS.md files in apps/ and libs/, and knowledge embedded in .github/skills/ and .github/agents/. Activate this skill when the user mentions syncing docs after a PR or commit, asks "what docs need updating?", says "update knowledge", references a big feature that just landed ("there was a big update in commit X"), or runs the staleness check script and sees stale files. Also activate proactively when you notice an AGENTS.md file is missing for a project that was just created, or when a skill references a pattern that no longer matches the source code. Do NOT wait for the user to explicitly say "knowledge sync" — if code has changed and docs might be stale, this skill applies immediately.
|
Knowledge Sync
The goal is to keep every piece of AI-agent documentation accurate and up-to-date so that any
agent can work confidently in any project without re-discovering facts that are already known.
Four layers of documentation to maintain:
- Root
AGENTS.md — workspace-wide: apps list, libs list, run commands, shared conventions
- Per-project
AGENTS.md — in apps/<name>/ and libs/<name>/: routing, services, state, gotchas
- Skills & agents in
.github/skills/ and .github/agents/ — patterns, idioms, workflows
- Product knowledge in
.github/skills/product-knowledge/ — docs repo (../docs) + live API specs. Has its own external source of truth; always check as part of every sync.
Workflow
Step 1 — Determine Scope
Ask yourself (or confirm with the user) which of these applies:
| Scope | When to use | Git command |
|---|
| Single commit | User names a commit hash | git show <hash> --name-only |
| Branch diff | Reviewing a PR or feature branch | git diff main...HEAD --name-only |
| Full audit | Periodic maintenance or "everything feels stale" | Run the staleness script (see Step 2) |
| Just new apps/libs | After a scaffold-only change | Check for missing AGENTS.md files |
Default to git diff main...HEAD --name-only if no explicit scope is given.
Step 2 — Detect Staleness
Run the staleness check script to find outdated docs:
.github/skills/knowledge-sync/scripts/check-staleness.sh
Or manually: for each project, check if its AGENTS.md is older than the newest source file:
find apps/auth/src -newer apps/auth/AGENTS.md -name "*.ts" 2>/dev/null | head -5
for dir in apps/*/ libs/*/; do
[ ! -f "${dir}AGENTS.md" ] && echo "MISSING: ${dir}AGENTS.md"
done
Step 2b — Check Product Knowledge Staleness (ALWAYS RUN)
This is mandatory on every sync — product knowledge has an external source of truth that is invisible to git diff on this repo.
LAST_COMMIT=$(python3 -c "import json; d=json.load(open('.github/skills/product-knowledge/meta.json')); print(d['docs_repo']['last_commit'])")
if [ -d "../docs" ]; then
cd ../docs && git fetch && git log ${LAST_COMMIT}..origin/main --oneline
cd -
else
echo "docs repo not found at ../docs — skipping docs staleness check"
fi
for spec in global nua nucliadb zone; do
STORED=$(python3 -c "import json; d=json.load(open('.github/skills/product-knowledge/meta.json')); print(d['api_specs']['${spec}']['etag'])")
CURRENT=$(curl -sI "https://cdn.rag.progress.cloud/api/${spec}/v1/api.yaml" | grep -i 'etag:' | tr -d '\r' | awk '{print $2}')
echo "${spec}: stored=${STORED} current=${CURRENT}"
done
If either check shows changes, add the affected references/ files to your work queue (see the Product Knowledge Staleness table in Step 3 for the full mapping). If both are up to date, proceed to Step 3.
Step 3 — Build the Staleness Map
Given the list of changed files, populate this map:
| Changed path | Documentation to update | Priority |
|---|
apps/<X>/ (new folder) | Create apps/<X>/AGENTS.md + add row to root AGENTS.md | CRITICAL |
apps/<X>/src/app/*routing* | Update routing tree in apps/<X>/AGENTS.md | HIGH |
apps/<X>/src/app/*guard* | Update guards section in apps/<X>/AGENTS.md | HIGH |
apps/<X>/src/app/*.state.ts | Update state section in apps/<X>/AGENTS.md | HIGH |
apps/<X>/ (general changes) | Review apps/<X>/AGENTS.md for accuracy | MEDIUM |
libs/<X>/ (new folder) | Create libs/<X>/AGENTS.md + add row to root AGENTS.md | CRITICAL |
libs/<X>/ (general changes) | Review libs/<X>/AGENTS.md | MEDIUM |
libs/sdk-core/src/lib/ | Review .github/skills/api-sdk/SKILL.md for stale API patterns | HIGH |
libs/sistema/ | Review .github/skills/design-system/SKILL.md for stale component names | MEDIUM |
libs/pastanaga-angular/ | Review .github/skills/design-system/SKILL.md | MEDIUM |
libs/user/ auth flows | Review .github/skills/angular-patterns/SKILL.md auth section | MEDIUM |
libs/user/src/assets/i18n/ | Review .github/skills/i18n-patterns/SKILL.md | LOW |
New file in .github/skills/ | Update .github/copilot-instructions.md skills list | CRITICAL |
New file in .github/agents/ | Update .github/copilot-instructions.md agents list | CRITICAL |
charts/ or docker/ | Review root AGENTS.md deployment section if one exists | LOW |
Product Knowledge Staleness
Handled in Step 2b above. If new docs commits or changed ETags were found there, use this table to map them to the correct reference files:
| Stale source | Action | Priority |
|---|
Docs repo: new commits touching docs/agentic/ | Update references/agentic-rag.md | HIGH |
Docs repo: new commits touching docs/rag/ | Update references/search-and-rag.md | HIGH |
Docs repo: new commits touching docs/ingestion/ | Update references/ingestion.md | HIGH |
Docs repo: new commits touching docs/management/ | Update references/management.md | MEDIUM |
Docs repo: new commits touching docs/rag/llms.md or advanced/models.md | Update references/llms-and-models.md | MEDIUM |
API spec ETag changed (global) | Re-download references/api-specs/global.yaml | HIGH |
API spec ETag changed (nua) | Re-download references/api-specs/nua.yaml | HIGH |
API spec ETag changed (nucliadb) | Re-download references/api-specs/nucliadb.yaml | HIGH |
API spec ETag changed (zone) | Re-download references/api-specs/zone.yaml | HIGH |
After updating, always refresh meta.json with the new commit hash, ETags, and updated_at:
cd ../docs && git rev-parse HEAD
curl -sI "https://cdn.rag.progress.cloud/api/{spec}/v1/api.yaml" | grep -i etag
Also update the "last updated" references in SKILL.md's "Keeping This Skill Up-to-Date" section.
Content ROI Quick Reference
Use this when deciding what belongs in an AGENTS.md. The full detailed framework lives in
.github/skills/agents-review/SKILL.md, but these criteria cover the most common decisions.
Core test: "Can an agent discover this in under 5 seconds by reading the source? If yes, skip it."
High ROI — Always Include
- Non-obvious invariants and runtime constraints — things that look like bugs but are intentional
- Custom architecture patterns unique to the project — not inferable from filenames alone
- Guards with their enforced conditions — agents will accidentally route around unknown guards
- File structure tree with one-line annotations
- Run commands —
nx serve/test/build with the exact project name
- Flag interactions and mutual exclusions — cannot be found without running code
- Intentional divergence from workspace norms — hash routing, eslint-disable on purpose, etc.
- Critical API usage distinctions — when to use one method vs another, why something emits multiple values
Low ROI — Skip These
- Method signature tables — agents read source directly
- Model/interface property lists — duplication of
*.models.ts
- Constants and enum value lists — greppable in under 2 seconds
- External dependency tables — already in
package.json
- Integration tutorials / README content — AGENTS.md is for contributors, not integrators
- Public API re-export indexes — note the barrel and categories, don't list all symbols
- Boilerplate descriptions redundant with filenames
Token Budget Targets
| Project type | Target | Max |
|---|
| Small lib (< 10 source files) | ~1,000 tokens | 2,000 |
| Medium lib or app | ~2,000 tokens | 4,000 |
Large lib (libs/common, libs/core) | ~3,000 tokens | 5,500 |
Files above max almost certainly duplicate source. Keep conventions and structure; cut method tables.
Step 4 — Execute Updates
Work through the staleness map from CRITICAL → HIGH → MEDIUM → LOW.
4a. New project — create AGENTS.md
If a new app or lib was created and has no AGENTS.md:
- Read the project's
project.json, routing files, main module/component tree, and key services
- Write the file from scratch, applying the Content ROI Quick Reference above — include high-ROI items (guards, structure tree, run commands, non-obvious constraints), skip low-ROI items (method tables, model lists, dependency tables). Use the
agents-review skill for the full evaluation framework if needed.
- Then add a row for the project in the root
AGENTS.md apps or libs table
4b. Existing project — update AGENTS.md
If source files changed in a project that already has an AGENTS.md:
- Read the diff for that project:
git diff <scope> -- apps/<X>/
- Read the current
apps/<X>/AGENTS.md
- Identify which facts are now wrong or missing (routing changes, renamed services, new guards)
- Edit the file in-place — do not rewrite sections that are still accurate
- Verify every class name, method name, and file path mentioned still exists in source
- Apply the Content ROI Quick Reference above — actively remove any low-ROI content (method signature tables, model property lists, dependency tables, integration tutorials) that snuck in. Use the
agents-review skill for the full evaluation framework if the file needs a deeper overhaul.
4c. Skills and agents — update inline knowledge
If a skill's documented patterns no longer match the source, update that skill directly.
Key signals that a skill is stale:
- A class or method name it references was renamed (check with
grep -r "OldName" src/)
- A route path it documents was changed
- A new pattern was introduced that contradicts the skill's guidance (e.g. new state management approach)
- An import alias was changed in
tsconfig.base.json
Do NOT rewrite skills speculatively — only update what is verifiably wrong.
4d. Root AGENTS.md
The root AGENTS.md needs updating when:
- A new app or lib is added (add a row to the table)
- An app is removed or renamed (update the table)
- A workspace-wide convention changes (e.g. switching test runner, changing package manager)
- Running commands change (ports, build commands, etc.)
Step 5 — Report
After completing updates, produce a concise summary:
## Knowledge Sync Report
**Scope:** <commit hash / branch / full audit>
**Changed projects detected:** <comma-separated list>
### Created
- <file path> — <one line reason>
### Updated
- <file path> — <what changed>
### Verified accurate (no changes needed)
- <file path>
### Skipped / Could not verify
- <file path> — <reason>
### Automation reminder
<Any files still stale that require manual verification, e.g. skill files that may reference
outdated patterns but the change was too subtle to verify automatically.>
Source-to-Docs Mapping Reference
Use this when you need to reason about which skill or agent is the authoritative owner of a
given piece of knowledge:
| Source of truth | Authoritative doc |
|---|
libs/sdk-core/src/lib/ | .github/skills/api-sdk/SKILL.md |
libs/sistema/ | .github/skills/design-system/SKILL.md |
libs/pastanaga-angular/ | .github/skills/design-system/SKILL.md |
libs/user/ (auth flows) | .github/skills/angular-patterns/SKILL.md + apps/auth/AGENTS.md |
*.state.ts patterns | .github/skills/angular-patterns/SKILL.md |
*.spec.ts patterns | .github/skills/testing-patterns/SKILL.md |
| RxJS usage in services | .github/skills/rxjs-patterns/SKILL.md |
libs/*/src/assets/i18n/ | .github/skills/i18n-patterns/SKILL.md |
nx.json, project.json | .github/skills/nx-monorepo/SKILL.md |
| App routing trees | Per-project AGENTS.md routing section |
| Guards | Per-project AGENTS.md gotchas/guards section |
| Feature flags | Per-project AGENTS.md gotchas section |
../docs repo | .github/skills/product-knowledge/SKILL.md + its references/ |
| API specs (global/nua/nucliadb/zone) | .github/skills/product-knowledge/references/api-specs/ |
Workspace Indexing
VS Code can index the workspace to help Copilot find code it hasn't seen.
This is complementary to AGENTS.md, not a replacement:
| Feature | Workspace Index | AGENTS.md |
|---|
| Finds any symbol by name | ✅ | ❌ |
| Understands architecture intent | ❌ | ✅ |
| Knows routing tree | ❌ (infers poorly) | ✅ |
| Knows non-obvious gotchas | ❌ | ✅ |
| Knows which guard enforces what | ❌ | ✅ |
| Costs tokens per query | Yes (reads file content) | No (already in context) |
Recommendation: Enable workspace indexing — it helps Copilot resolve symbols it cannot find
from context alone. But never rely on it for architectural or convention knowledge; that belongs
in AGENTS.md. Well-written AGENTS.md files reduce token usage by providing curated facts
instead of requiring the AI to scan source files on every turn.
Automation: Never Forget to Sync
Run the git hook installer to get automatic staleness reminders after every git pull or merge:
.github/skills/knowledge-sync/scripts/install-hooks.sh
What the hook does:
- After
git pull or git merge, runs the staleness check
- If stale docs are found, prints a specific list to the terminal
- Does NOT block your workflow — just prints a reminder
To trigger a full knowledge sync manually:
.github/skills/knowledge-sync/scripts/check-staleness.sh
You can also add a VS Code task — see .github/skills/knowledge-sync/scripts/vscode-task.json
for a ready-made task definition to drop into .vscode/tasks.json.
Common Patterns to Watch For
When reviewing changed diffs for knowledge-impacting changes, look for:
- New
app.module.ts or new standalone app.component.ts → new app bootstrapped
- New
*-routing.module.ts or Routes array changes → routing tree changed
- New
*.guard.ts → guards section needs updating
- New
*.state.ts or new BehaviorSubject fields → state section may need updating
- Changes to
index.ts barrel exports → public API of a lib changed
- New
environment*.ts files → environment configuration may have changed
- Changes to
tsconfig.base.json paths → path aliases changed, update root AGENTS.md
- New
i18n/*.json keys → check i18n-patterns skill if key naming convention changed
- New
@NgModule or removal of @NgModule → module architecture changed
