AGENT SKILL

explain-codebase-concept

Onboard to how one Ahentic concept, feature, or subsystem is wired — chat summary plus visual HTML walkthrough (optional durable copy under docs/walkthroughs/).

License 许可
GPL-3.0
所属仓库
gambitph/Ahentic
最近更新
2026-08-15
Stars
★ 0
Forks
0

01 前言 Front Matter

name
explain-codebase-concept
description
Onboard to how one Ahentic concept, feature, or subsystem is wired — chat summary plus visual HTML walkthrough (optional durable copy under docs/walkthroughs/).
disable-model-invocation
true

02 资源文件 2

03 SKILL.md 正文

Explain Codebase Concept

Onboard a repo / Ahentic beginner (stack-literate: WP/JS assumed) to one concept, feature, or subsystem so they can contribute — extend, fix bugs, or add related behavior — without inventing a second architecture doc.

Deliverables (every run): chat summary and a self-contained HTML walkthrough (Tailwind + Mermaid).
Authority: compose and cite the doc ladder + live code. PRD / CONTRACT win on disagreement. Flag drift; offer doc fixes — do not auto-write product law.
Not this skill: deepening/refactor candidates (improve-codebase-architecture), bug hunts (diagnosing-bugs), or a whole-product tour (point at docs/architecture.md and offer a menu of slices).

See HTML-REPORT.md for the report scaffold and section rules. Human index: docs/agents/explain-concept.md.

Process

1. Scope

Done when: one coherent slice is named in a single sentence (concept / flow / subsystem), or the user picked from a short menu.

  • If the ask maps cleanly to CONTEXT.md, docs/architecture.md, or a CONTRACT.md → state the assumed scope and proceed.
  • If several slices fit → offer a short menu (A / B / C), not a full grill.
  • If they ask to “explain all of Ahentic” → point at docs/architecture.md; offer 3–5 high-value follow-on concepts. Do not generate a mega-walkthrough.

Normalize subsystem / filename asks into the runtime path that makes the concept real (sidebar → REST → orchestrator → …), not a folder dump.

2. Explore

Done when: glossary terms for the slice are loaded, the relevant CONTRACT + how-it-works are read, the live path is traced, and any doc↔code drift is noted.

  1. Docs-first ladder (skip missing files silently): CONTEXT.md → docs/architecture.md → relevant src/**/CONTRACT.md + colocated how-it-works → PRD/ADR only if the slice is about intended behavior or a recorded trade-off.
  2. Code trace — use the Agent tool with subagent_type=Explore to follow the runtime path end-to-end. Neighbors that are not load-bearing stay black boxes with pointers to their CONTRACT / how-it-works.
  3. Collect primary files and key symbols for the Cast and Step-through (prefer a tight set over exhaustiveness).
  4. Note contribution hooks: usual touch path, ability-checklist / tests / catalogues that must stay in sync when this slice changes.

Use CONTEXT.md vocabulary for domain names. Use codebase-design terms (module, seam, interface, …) only in Neighbors / Change map when they help a contributor locate a change. Keep ELI5 in plain English.

3. Write the HTML walkthrough

Done when: the file exists, opens in the browser, and contains all nine mandatory sections in order (see HTML-REPORT.md).

  1. Resolve temp dir from $TMPDIR, else /tmp (or %TEMP% on Windows).
  2. Write $TMPDIR/concept-walkthrough-<slug>-<timestamp>.html (slug from the concept name; kebab-case).
  3. Open it: open <path> (macOS), xdg-open <path> (Linux), start <path> (Windows).
  4. Tell the user the absolute path.

Empty sections still appear as a one-liner (e.g. “No doc drift found”) so the shape stays recognizable.

4. Chat handoff

Done when: the user has a short summary in-thread and clear next offers.

In chat (≈5–8 lines):

  • What the concept is (one sentence)
  • The runtime path in plain words
  • Where to look first (2–4 primary files)
  • How you’d usually change it (one sentence)
  • Absolute path to the HTML file

Then offer:

  • (a) zoom a black-boxed neighbor into its own walkthrough
  • (b) walk a related concept
  • (c) fix doc drift (if any were listed)
  • (d) save a durable copy under docs/walkthroughs/ for humans (see below)

5. Durable docs (optional)

Done when: either the user declined, or docs/walkthroughs/<slug>.html is written, the folder README index lists it, and the HTML banner states it is pedagogical — not product law.

Default output stays in temp. When the user asks to keep / commit / add as docs:

  1. Write (or refresh) docs/walkthroughs/<slug>.html with the same mandatory outline and a visible banner: pedagogical walkthrough; PRD / CONTRACT / how-it-works win; regenerate when the slice drifts.
  2. Update docs/walkthroughs/README.md index (slug, title, one-line summary, date).
  3. Do not git commit unless the user explicitly asks. Do not invent product “should” in the walkthrough — cite PRDs; absorb real product gaps via domain-modeling / PRD edits only when the user accepts that offer.
  4. Do not replace or duplicate CONTRACT.md / colocated how-it-works as the source of truth; the walkthrough points at them.

Walkthroughs are supporting orientation maps (cross-stack, beginner-shaped). They are not a fourth product-law surface (see ADR-0001 / PRD index).

Collision guard

Ask Skill
How does X work / onboard me on X This skill
Deepen / shallow modules / architecture review improve-codebase-architecture
Something’s broken / failing diagnosing-bugs
Whole-system map only docs/architecture.md (no mega-HTML)

04 同仓库更多 Skills

gambitph
gambitph/Ahentic

writing-for-agents

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

★ 0
gambitph
gambitph/Ahentic

wp-rest-api

Use when building, extending, or debugging WordPress REST API endpoints/routes: register_rest_route, WP_REST_Controller/controller classes, schema/argument validation, permission_callback/authentication, response shaping, register_rest_field/register_meta, or exposing CPTs/taxonomies via show_in_rest.

★ 0
gambitph
gambitph/Ahentic

wp-project-triage

Use when you need a deterministic inspection of a WordPress repository (plugin/theme/block theme/WP core/Gutenberg/full site) including tooling/tests/version hints, and a structured JSON report to guide workflows and guardrails.

★ 0
gambitph
gambitph/Ahentic

wp-plugin-directory-guidelines

Use when reviewing WordPress plugins for GPL compliance, checking license headers or compatibility, evaluating upsell/freemium/trialware patterns, validating plugin naming or trademark rules, checking plugin slugs, understanding why a plugin was rejected from WordPress.org, or answering any question about the 18 WordPress.org Plugin Directory guidelines — even if the user doesn't mention 'guidelines' explicitly.

★ 0
gambitph
gambitph/Ahentic

wp-plugin-development

Use when developing WordPress plugins: architecture and hooks, activation/deactivation/uninstall, admin UI and Settings API, data storage, cron/tasks, security (nonces/capabilities/sanitization/escaping), and release packaging.

★ 0
gambitph
gambitph/Ahentic

wp-performance

Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification.

★ 0