SuperAPI AI Directory

extract-glossary

General & other

View repository

Updated 10-15 21:48

About this skill

extract-glossary

A skill for creating knowledge from a specified codebase that serves both as human onboarding material and as knowledge to prevent AI from re-confirming the same things. Deliverables are divided into a "glossary," a "repository implementation map," a "technical architecture," and "small Mermaid diagrams."

Purpose

  • Enable new participants to quickly read industry terminology, internal organization terminology, and implementation-specific names.
  • Enable AI agents to work by referring to existing materials without asking about the same terms or architecture every time.
  • Tie explanations of the codebase to evidence in README/docs/schema/IaC/code rather than speculation.

What is accepted as input

Any of the following is acceptable.

  • Local checkout path: ../repo, ~/ghq/github.com/org/repo
  • GitHub URL: https://github.com/org/repo
  • A list of multiple repositories
  • A GitHub organization name and filtering conditions
  • Output destination: docs in an existing repo,.claude/skills/<domain>-glossary/, or any set of Markdown files

If the input is ambiguous, first confirm the candidate repos and output destination. However, if they can reasonably be identified from local or GitHub sources, begin exploration.

Standard structure of deliverables

When creating this as a skill, use the following as the basis.

<domain>-glossary/
├── SKILL.md
├── references/
│   ├── glossary.md
│   ├── repository-map.md
│   └── architecture.md
└── assets/
    └── architecture-diagrams.md

When creating it as ordinary docs, maintain the same division.

File Role
glossary.md Glossary. Separate industry terminology, domain terminology, internal organization abbreviations, and implementation-specific names.
repository-map.md Summarize each repo's responsibilities, main directories, entry points to look at, and external dependencies.
architecture.md Summarize the tech stack, data flow, infrastructure, deployment, and operational cautions.
architecture-diagrams.md Mermaid diagrams. Divide them into small diagrams by purpose rather than one huge diagram.
SKILL.md Write only which references AI should read and when. Do not pack in too much detail.

Investigation procedure

1. Determine the scope

  1. Confirm the target repo/org and target branch/commit.
  2. If there is a local checkout, confirm git remote -v と git rev-parse HEAD .
  3. When looking at a repo on GitHub, confirm the default branch and URL.
  4. In deliverables, include GitHub URLs rather than machine-specific local paths.

You may investigate using local paths, but in the final deliverables convert them as follows.

/Users/me/ghq/github.com/org/repo/docs/foo.md
-> https://github.com/org/repo/blob/<branch-or-sha>/docs/foo.md

2. Build a corpus

What to read with priority:

  • README.md, CLAUDE.md, AGENTS.md, docs/, adr/, design/, architecture/
  • openapi.yaml, GraphQL schema, Protocol Buffers, SQL schema, migration, DB docs
  • Terraform, Packer, CDK, SAM, Helm, Kubernetes, GitHub Actions, deploy docs
  • package manifests: package.json, go.mod, Cargo.toml, composer.json, pyproject.toml, etc.
  • entrypoints and routing: main.*, routes.*, controller/resolver/handler files

What to avoid:

  • node_modules, vendor, generated code, build artifacts, minified files, lockfile details
  • Using large logs or fixtures as the main information source
  • Making assertions based only on names

For exploration, first use rg --files と rg .

3. Extract terminology candidates

Always classify terminology.

Classification Example Criteria
Industry terminology RTB, SSP, VAST, OAuth, ETL Standard and industry terms understandable outside the company.
Domain terms Publisher, Campaign, Order, Placement Concepts in the business domain. Even if they are external terms, they have meaning within the product.
Organization-internal terms Abbreviations, former names, team-specific names Appears in README/docs/code but is not an external standard.
Implementation-specific names service names, directory names, table prefixes Components within the codebase.
Infrastructure terms ECS, Snowflake, Meilisearch, Packer Terms that need to be understood as part of the technical foundation.

Each term should include the following.

  • Term
  • Meaning
  • Classification
  • Main implementation/reference repo
  • Source URL
  • Notes or easily confused terms
  • Confidence: confirmed / inferred / needs-check

inferred is an inference from the name/placement. Do not state it as a definitive statement.

4. Create a repository implementation map

Summarize the following for each repo.

  • What is implemented
  • Main components/directories
  • Tech stack
  • Entry-point README/docs/source files
  • Communication/data dependencies with other repos
  • DB/schema/API/protocol boundaries
  • Files to look at first when investigating

For relationships among multiple repos, first create a rough repo-level correspondence table, then break down only the important repos to the component level.

5. Summarize the technical architecture and infrastructure architecture

At minimum, write the following perspectives separately.

  • runtime request flow
  • config / master data flow
  • batch / ETL / report flow
  • auth / identity / user data flow
  • DB / search / cache / object storage
  • cloud resources and IaC ownership
  • deploy / rollback / observability
  • local development prerequisites

For cloud architecture, separate "which services are used" from "which repo manages them."

How to create Mermaid diagrams

Do not make one huge diagram. Make one diagram per topic.

Recommended small diagrams:

Diagram Purpose
repository overview Look only at the rough responsibilities and dependencies among repos.
config/data path See the flow of admin screen and DB settings reaching runtime.
request sequence See the runtime communication of actual requests. Prefer sequenceDiagram.
integration entries Look at each entry point such as external partners, webhooks, and protocol endpoints.
infra ownership See what Terraform/CDK/SAM etc. manage.
data pipeline See the flow of log/report/warehouse/search/indexing.

Diagram constraints:

  • Aim for around 10 nodes and around 15 edges per diagram.
  • Mermaid の subgraph Do not make it too deep. If overlaps or long crossing lines appear, split it.
  • Keep edge labels short. Move explanations to the body text.
  • Create detailed protocol/schema diagrams only when the user explicitly requests them.
  • Do not mix artifacts, schemas, and runtime communication in the same diagram.
  • If the rendered result is hard to read, increase the number of diagrams and split them.

Source/URL rules

  • Do not include local absolute paths or ../repo in deliverables.
  • Use a GitHub URL, official docs URL, or a persistent URL specified by the user as the reference source.
  • Even when investigating with a local checkout, convert the remote URL and branch/commit into a GitHub URL.
  • Even if the URL may not be readable due to a private repo, include a URL that readers can follow if they have the necessary permissions.
  • If uncertain, use needs-check and clearly indicate the weakness of the evidence.

Quality Check

Before submitting, confirm the following.

# ローカルパス漏れ
rg -n -F '../' <output-dir>
rg -n '/Users/|/home/' <output-dir>

# Markdown の基本チェック
git diff --check

# Mermaid block 数と fence 対応
rg -n '(^```mermaid|^```$|^flowchart|^sequenceDiagram)' <diagram-file>

# mmdc があればレンダリング確認
command -v mmdc && mmdc -i <diagram-file> -o /tmp/diagrams.svg

mmdc If there is no , state that in the final report.

Notes When Responding

  • Separate "based on the current repo" from "inference".
  • Do not mix industry terminology with organization-specific terminology.
  • If the deliverable is for onboarding, be sure to include the reading order and investigation entry points.
  • When making it into an AI skill,SKILL.md keep thin, and move details to references/ .
  • Proceed to the git publish flow only if the user requests commit/push/PR.