AGENT SKILL

ag-context-discovery

Discover and load all relevant context for the current task. Lists feature group nested files with full paths, loads process/context/ files by domain routing. Called at the start of every agent session.

License 许可
MIT
最近更新
2026-08-02
Stars
★ 0
Forks
0

01 前言 Front Matter

name
ag-context-discovery
layer
contract
description
Discover and load all relevant context for the current task. Lists feature group nested files with full paths, loads process/context/ files by domain routing. Called at the start of every agent session.
trigger_keywords
context discovery, load context, feature folder files, context routing discovery

02 资源文件 5

03 SKILL.md 正文

ag-context-discovery

When to Apply

Use this skill when working with ag-context-discovery workflows, tasks, or system specifications.

How to Use

Refer to the workflow instructions and command references detailed below.

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Discover and load all relevant context for the current task. This skill lists feature group nested files with full paths and loads process/context/ files by domain routing table. It is the canonical context-loading entrypoint for every agent session.

When To Invoke

At the start of every agent session (research, innovate, plan, validate, execute, update-process, fast-mode). Also at the start of any skill that needs repo context before operating.

Frontmatter Schemas

Document the canonical schemas for three file types used across the repo. These schemas enable frontmatter-aware routing and filtering.

Context file frontmatter schema:

name: context:{slug}
description: "one-line scope — used by ag-context-discovery for routing"
keywords: comma, separated, task, vocabulary, terms # drives grep-first keyword routing
related: [context: { other-slug }, context: { another-slug }] # sibling/cross-group links (optional)
date: dd-mm-yy
  • keywords — strongly recommended, non-empty. Comma-separated task-vocabulary terms an agent would use to describe a task this doc serves (e.g. session, token, refresh, jwt, login). This is the match surface for discover-context.mjs --match; weak/absent keywords are why a relevant doc never gets routed to. Lint WARNS when empty (so existing projects don't break on sync) — backfill at UPDATE-PROCESS.
  • related — OPTIONAL list of context:{slug} values for sibling docs that are usually needed together (the markdown-native equivalent of cross-links). Every slug listed MUST resolve to a real context: doc; dangling links fail lint. Discovery follows these after the primary match so a task touching two domains loads both.

Plan file frontmatter schema:

name: plan:{slug}
description: "one-line scope and feature"
date: dd-mm-yy
feature: { feature-folder-name }
phase: "{phase-id}" # optional, for phase program plans only

Report file frontmatter schema:

name: report:{slug}
description: "one-line scope"
date: dd-mm-yy
metadata:
  node_type: memory
  type: report
  feature: { feature-folder-name }
  phase: { phase-id }

Invocation

Primary method — run the auto-discovery script. It lists all nested files under process/context/, process/development-protocols/, process/general-plans/active/, and (with --feature) the feature folder, extracting ONLY the leading YAML frontmatter block of each .md file (no whole-file reads):

node .claude/skills/ag-context-discovery/scripts/discover-context.mjs [--feature <name>] [--json]

The script groups output into: context files with frontmatter, protocol files, feature files by subfolder, active general plans, and files-without-frontmatter (path only). It never throws on a missing root and exits 0 unless given a bad flag. Use --json for a machine-readable object. Prefer this over manually reading each file — it is deterministic and avoids loading huge files into context.

Keyword-first routing (deterministic, not judgment). When the task vocabulary does not obviously map to a routing-table row, do not guess — let the index do the matching:

node .claude/skills/ag-context-discovery/scripts/discover-context.mjs --match "update the user ORM model"

This tokenizes the task and ranks context docs by overlap with their frontmatter keywords, then appends any related: siblings of the top hits. Read the ranked docs in order. This is the fallback that fixes "the right doc existed but the agent walked past it."

Routing-table generation (drift-proof index). The "Current Root Entry Points" and "Current Context Groups" tables in all-context.md are GENERATED from frontmatter, not hand-authored — they live between <!-- GENERATED:routing --> / <!-- /GENERATED:routing --> markers. Rebuild them after any context-org change:

node .claude/skills/ag-context-discovery/scripts/discover-context.mjs --emit-routing   # rewrites the block
node .claude/skills/ag-context-discovery/scripts/discover-context.mjs --check-routing  # lint: block in sync?

The hand-authored Task Routing Table (task-type → file) stays editorial and is NOT generated.

Per task-folder artefact colocation, the script surfaces each task's plan, spec, reports, and references INSIDE its own {slug}_{date}/ task folder; the sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

Workflow (manual FALLBACK)

Use these steps only if the script above fails or is unavailable.

Step 1. Run find process/context/ -type f | sort and record all available context files.

Step 2. Run find process/development-protocols/ -type f | sort and record all protocol files.

Step 3. Read process/context/all-context.md to get the routing table and current feature list.

Step 4. If a feature name was provided as the argument, run find process/features/{feature}/ -type f | sort to list ALL artifacts across all subfolders (active/, completed/, backlog/, plus any legacy reports/, references/). Surface full file paths — not just folder names. Per task-folder artefact colocation, expect each task's plan, spec, reports, and references INSIDE its own {slug}_{date}/ task folder; the sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

Step 5. If no feature name was provided, run find process/general-plans/active/ -type f | sort to surface any active plans relevant to the current task. Note: plan files are inside {slug}_{date}/ task subfolders — look one level deep for *_PLAN_*.md files.

Step 6. From the routing table in all-context.md, identify the context group files relevant to the current task domain (e.g. tests, container, infra, skills, uxui, workflows). Do NOT read every context file — only the ones the routing table says apply to this domain. If no row obviously matches, run discover-context.mjs --match "<task>" and use its ranked keyword hits instead of guessing.

Step 7. Read the domain context file(s) identified in step 6. Each all-{group}.md is a router — after reading it, follow its routing table to load the deeper domain file(s) for the task. Then load any related: siblings of the docs you read — a task spanning two domains (e.g. auth + tests) needs both, and related is how the cross-domain link is declared.

Step 8. Frontmatter extraction: For each file in the discovered set, if the file has YAML frontmatter (a --- block at top), extract the name, description, and date fields. Surface in output as "[path] (name: X — description: Y)". Files without frontmatter: surface path only (no error, do not skip them).

Step 9. Report: full file listing for the feature folder (if applicable), active context files loaded, and any open gaps in context that would block the task.

Output Format

Context file paths with frontmatter:
  process/context/skills/skill-apps.md (context:skill-apps — Skill app runtime, vite architecture, ctx-gateway, deployment)
  process/context/tests/all-tests.md (context:all-tests — Test routing, runner split, debugging procedures)

Plan files with frontmatter:
  process/features/{feature}/completed/{slug}_{date}/{slug}_PLAN_{date}.md (plan:{plan-name} — short description...)

Files without frontmatter (path only):
  process/context/ui/design.md

Context Envelope

At session start, every inner-loop agent (research / plan / execute / update-process) emits a Context Envelope — a 10-field table capturing the orientation an agent needs to act. All 10 fields are required (use best-effort values; TBD — [reason] when not yet determinable). The fields MUST appear in the EXACT canonical C-2 order below — identical order in this SKILL and in all four inner-loop agents:

# Field Value
1 feature feature folder name (or TBD)
2 phase current RIPER phase (RESEARCH / INNOVATE / PLAN / PVL / EXECUTE / EVL / UPDATE-PROCESS)
3 session-goal one-line goal from the /goal block
4 branch current git branch
5 worktree worktree path (or main)
6 context-group relevant process/context/ group (or none)
7 blast-radius-packages packages/paths in scope (comma-separated or TBD)
8 active-plan selected plan file path (or none)
9 test-runner test runner(s); multi-runner uses pipe-delimited DISPLAY format bun test | vitest
10 validate-contract validate-contract path (or none)

Canonical order (memorize): feature → phase → session-goal → branch → worktree → context-group → blast-radius-packages → active-plan → test-runner → validate-contract.

test-runner multi-runner rule: the pipe-delimited bun test | vitest value is a DISPLAY convention only. The phase-loop workflow template (.claude/skills/ag-generate-phase-program/templates/phase-loop-workflow-template.js) expands it into SEQUENTIAL test steps (bun test THEN vitest) — a literal bun test | vitest shell pipe is NEVER emitted or run. See 03-session-start.md for the matching field table.

Frontmatter-Aware Routing

After collecting file paths, read YAML frontmatter from each file where present.

Surface the following fields alongside path: name, description, keywords, related, date, type, feature, phase.

Use the description and keywords fields for routing decisions instead of filename inference.

Group plan files by their feature field value.

Filter and sort by type field (context / plan / report / references).

Discover all nested files under feature group subdirs: active/, completed/, backlog/, reports/, references/.

Files without frontmatter: surface path only (no error), do not skip them.

Important Rules

  • This skill is INDEPENDENT — it does not invoke other skills.
  • Read all-context.md as a router, then load the deeper file(s). Do not treat all-context.md as sufficient on its own.
  • Always produce the full find output, not a summary. The exact file paths are the output.
  • Never hardcode context file paths — always discover via the find command and the routing table in all-context.md.

References

04 同仓库更多 Skills

ngxccc
ngxccc/agent-skills-kit

zustand

Rules and standards for state management using Zustand in React and Next.js. Use when implementing client-side stores, persistence with localStorage, or preventing SSR hydration mismatch.

★ 0
ngxccc
ngxccc/agent-skills-kit

zod

Zod v4 schema validation best practices. Use when defining schemas, utilizing safeParse, or customizing error messages.

★ 0
ngxccc
ngxccc/agent-skills-kit

upstash-ratelimit

Rules, standards, and references for rate limiting in serverless environments using Upstash Ratelimit. Use when implementing rate limiting, configuring Upstash Redis, or handling request blocking.

★ 0
ngxccc
ngxccc/agent-skills-kit

ui-design

UI/UX and frontend design best practices guidelines (formerly frontend-design). This skill should be used when writing, reviewing, or designing frontend code to ensure accessibility, performance, and usability. Triggers on tasks involving HTML structure, CSS styling, responsive layouts, form design, animations, or accessibility improvements.

★ 0
ngxccc
ngxccc/agent-skills-kit

typescript

TypeScript performance, tsconfig, type errors, async patterns — triggered when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.

★ 0
ngxccc
ngxccc/agent-skills-kit

typescript-refactor

TypeScript and TSX refactoring and modernization guidelines from a principal specialist perspective, current to TypeScript 6.0 and React 19. This skill should be used when refactoring, reviewing, or modernizing TypeScript or React/TSX code for type safety, compiler performance, and idiomatic patterns. Triggers on tasks involving type architecture, narrowing, generics, discriminated unions, error handling, React component and hook typing, or migration to modern TypeScript features (satisfies, using, const type parameters, inferred type predicates, isolatedDeclarations, erasable syntax, import attributes).

★ 0