shadow-frog
Use a shadow knowledge base to understand any codebase. The .shadow/ directory mirrors the source tree with markdown files containing behavioral insights — known bugs, edge cases, implicit contracts, and user preferences. Always check the shadow before editing, debugging, or investigating code. When the user shares important context, write it to the shadow immediately. Invoke shadow-frog-init to create it, shadow-frog-update to refresh it, shadow-frog-dream for autonomous exploration, shadow-frog-meditate for shadow hygiene, or shadow-frog-viewer to browse it.
microsoft · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add microsoft/ShadowFrog --skill shadow-frog技能说明
name: shadow-frog description: >- Use a shadow knowledge base to understand any codebase. The .shadow/ directory mirrors the source tree with markdown files containing behavioral insights — known bugs, edge cases, implicit contracts, and user preferences. Always check the shadow before editing, debugging, or investigating code. When the user shares important context, write it to the shadow immediately. Invoke shadow-frog-init to create it, shadow-frog-update to refresh it, shadow-frog-dream for autonomous exploration, shadow-frog-meditate for shadow hygiene, or shadow-frog-viewer to browse it.
ShadowFrog
.shadow/ mirrors the source tree. Each source file has a .md shadow organized
by symbol. Each symbol section contains discoveries — behavioral insights anchored
to that code location.
Required Actions
Every time you work on code in a repo with .shadow/:
- Read
_prefs.mdfirst — it contains project-wide conventions, user preferences, and things the user explicitly wants to avoid. Violating a preference wastes the user's time. - Read
_cross/discoveries — these are the highest-value findings, spanning multiple files. List_cross/and read any files whose titles relate to the area you're working in. Cross-cutting discoveries reveal hidden contracts, interaction bugs, and design patterns that per-file shadows alone cannot capture. - Check
_dreams/for experiment results —_dreams/_index.mdlists autonomous exploration experiments. Read reports relevant to your task — they contain verified bug analyses, attempted fixes, and architectural insights. Dreams may contain knowledge not yet distilled into per-file shadows, so always check when investigating a bug or unfamiliar area. - Before editing any file: read its shadow (
.shadow/<path>.md), check_cross/for cross-cutting discoveries about it, and apply what you learn. The shadow contains known bugs, edge cases, and implicit contracts discovered by previous sessions. Note:_index.mddiscovery counts may be stale — always check per-file shadows and_cross/directly rather than relying solely on the index summary. - When the user explains something about code (gotcha, design intent,
warning, history): write a
source: userdiscovery to the shadow immediately. Do not ask where to put it — resolve thefile::symbolanchor yourself by searching_index.md, shadow files, and session context (current file, recent edits). - When the user states a preference or convention (not tied to any
specific file): write it to
_prefs.mdimmediately. - After code changes: run
/shadow-frog-update
Directory Layout
.shadow/
.shadowignore Gitignore-syntax file for excluding paths from the shadow
_index.md File list with symbol counts and discovery counts
_prefs.md Project-wide user preferences (not tied to any file/symbol)
_cross/ Cross-cutting discoveries (span multiple files)
<slug>.md One file per cross-cutting discovery (descriptive kebab-case name)
_meta/
state.json Last commit, timestamps, counts
_dreams/ Dream experiment archive (detailed reports + diffs)
_index.md Table of all experiments with verdicts
<YYYYMMDD-HHMMSSZ-slug>/ One folder per experiment
report.md Structured report with YAML frontmatter
patch.diff Full implementation diff against base_commit
<mirrored tree>/ Per-file shadows
file.py.md Organized by symbol
Reference Notation
Canonical format: file_path::symbol_name
Examples: src/auth.py::authenticate_user, src/auth.py::UserAuth.validate,
src/auth.py (file-level, no symbol)
The symbol name is the stable anchor.
Per-File Shadow Format
# Shadow: src/auth.py
**Language**: Python | **Lines**: 142 | **Last modified**: 2025-01-15
## File-Level
- This module has no __all__ — all top-level names are public.
_(verified, source: exploration)_
## `class UserAuth`
### `UserAuth.validate`
- Catches ALL exceptions and returns False — swallows
connection errors, making network failures look like invalid tokens.
_(verified, source: exploration)_
## `authenticate_user`
- Silently returns None on expired tokens. Callers must check.
_(verified, source: exploration, labels: [bug])_
Also involves: `src/middleware.py::require_auth`
## Cross-References
- [db-connection-lifecycle](../_cross/db-connection-lifecycle.md)
(involves `src/db/connection.py::ConnectionPool`, `src/api/routes.py::get_user`)
Heading format (hard rule — parsers depend on this):
- Top-level symbols (classes, functions, constants):
##heading with symbol in backticks - Nested symbols (methods):
###heading with symbol in backticks ## Cross-References— always last section
The viewer parser only matches the backtick form. A heading written as
### UserAuth.validate (no backticks) will have its discoveries
silently dropped from search/top output. Always wrap the symbol in
backticks, including for nested symbols.
Examples:
## `authenticate_user`
## `class UserAuth`
### `UserAuth.validate`
Cross-Cutting File Format (_cross/<slug>.md)
# Database connection lifecycle
**Category**: pattern
**Refs**:
- `src/db/connection.py::ConnectionPool.get`
- `src/auth.py::authenticate_user`
- `src/api/routes.py::get_user`
**Discovery**: All database access goes through a connection pool that
silently reconnects on failure. First request after DB restart is slow (~2s).
_(verified, source: exploration)_
Preferences File (_prefs.md)
Project-wide user preferences and conventions that are not tied to any specific file or symbol. These guide all agent work across the codebase.
# Preferences
- No backward compatibility — only keep the latest code, no shims or aliases.
_(source: user)_
-
阅读完整来源 ↗