How do I install the Mapping skill?

Run npx skillmds@latest add xiaolai/mapping in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Mapping safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Mapping?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Mapping free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Mapping?

xiaolai (@xiaolai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Mapping by xiaolai — Agent Skill

Name: Mapping
Author: xiaolai

File contents

Code-to-Doc Mapping

Overview

A mapping is a pair: (source_file, doc_file). The audit pipeline resolves all mappings before dispatching to agents. Four strategies are applied in priority order.

Strategy 1: Config-Based (Highest Priority)

User-defined mappings in .claude/docs-guardian/config.json:

{
  "mappings": [
    { "source": "src/auth/**/*.ts", "doc": "docs/api/auth.md" },
    { "source": "src/db/models/*.py", "doc": "docs/models/${name}.md" }
  ]
}

The ${name} placeholder expands to the source file's basename without extension.

Glob patterns are supported in source. The doc field can be a literal path or use ${name}.

Strategy 2: Framework-Derived

Each framework adapter knows its own mapping convention:

Framework	Convention
MkDocs	`mkdocs.yml` nav entries → doc paths under `docs_dir`
VitePress	`.vitepress/config` sidebar entries → doc paths
Docusaurus	`sidebars.js` entries → doc paths under `docs/`
Sphinx	`toctree` directives → `.rst` files under `source/`
Plain Markdown	Convention-based (see Strategy 3)

Strategy 3: Convention-Based

When no config or framework mapping exists, use naming conventions:

Source Path	Doc Path
`src/foo/bar.ts`	`docs/foo/bar.md`
`src/foo/bar.ts`	`docs/api/foo/bar.md`
`lib/foo.py`	`docs/foo.md`
`pkg/foo/bar.go`	`docs/foo/bar.md`
`src/foo/mod.rs`	`docs/foo.md`

Try each candidate in order. First existing file wins.

If no doc file exists for a source file, record it as unmapped (potential coverage gap).

Strategy 4: Inline-Doc (Lowest Priority)

Some symbols are documented inline (docstrings, JSDoc, godoc comments) rather than in separate doc files. When a source file has no external doc mapping but contains inline documentation:

Still count the inline docs toward coverage
Flag as INFO that docs are inline-only (not necessarily a problem)
If the framework expects external docs, flag as MEDIUM coverage gap

Mapping Output

Return an array of resolved mappings:

[
  {
    "source": "src/auth/login.ts",
    "doc": "docs/api/auth.md",
    "strategy": "config",
    "confidence": "high"
  },
  {
    "source": "src/utils/hash.ts",
    "doc": null,
    "strategy": "unmapped",
    "confidence": "none"
  }
]

---name: mappingdescription: Use when mapping source code files to their documentation counterparts — find which docs cover which code, detect gaps, and resolve doc-to-code relationships.---# Code-to-Doc Mapping## OverviewA **mapping** is a pair: `(source_file, doc_file)`. The audit pipeline resolves all mappings before dispatching to agents. Four strategies are applied in priority order.## Strategy 1: Config-Based (Highest Priority)User-defined mappings in `.claude/docs-guardian/config.json`:```json{ "mappings": [ { "source": "src/auth/**/*.ts", "doc": "docs/api/auth.md" }, { "source": "src/db/models/*.py", "doc": "docs/models/${name}.md" } ]}```The `${name}` placeholder expands to the source file's basename without extension.Glob patterns are supported in `source`. The `doc` field can be a literal path or use `${name}`.## Strategy 2: Framework-DerivedEach framework adapter knows its own mapping convention:| Framework | Convention ||-----------|-----------|| MkDocs | `mkdocs.yml` nav entries → doc paths under `docs_dir` || VitePress | `.vitepress/config` sidebar entries → doc paths || Docusaurus | `sidebars.js` entries → doc paths under `docs/` || Sphinx | `toctree` directives → `.rst` files under `source/` || Plain Markdown | Convention-based (see Strategy 3) |## Strategy 3: Convention-BasedWhen no config or framework mapping exists, use naming conventions:| Source Path | Doc Path ||-------------|----------|| `src/foo/bar.ts` | `docs/foo/bar.md` || `src/foo/bar.ts` | `docs/api/foo/bar.md` || `lib/foo.py` | `docs/foo.md` || `pkg/foo/bar.go` | `docs/foo/bar.md` || `src/foo/mod.rs` | `docs/foo.md` |Try each candidate in order. First existing file wins.If no doc file exists for a source file, record it as **unmapped** (potential coverage gap).## Strategy 4: Inline-Doc (Lowest Priority)Some symbols are documented inline (docstrings, JSDoc, godoc comments) rather than in separate doc files. When a source file has no external doc mapping but contains inline documentation:- Still count the inline docs toward coverage- Flag as `INFO` that docs are inline-only (not necessarily a problem)- If the framework expects external docs, flag as `MEDIUM` coverage gap## Mapping OutputReturn an array of resolved mappings:```json[ { "source": "src/auth/login.ts", "doc": "docs/api/auth.md", "strategy": "config", "confidence": "high" }, { "source": "src/utils/hash.ts", "doc": null, "strategy": "unmapped", "confidence": "none" }]```

Frequently asked questions

Mapping