7spade/black-tortoise

Overview

This skill is a navigable reference for the Black Tortoise TypeScript codebase. It helps you locate files, read source code, and understand project structure and implementation patterns. Use it to quickly map features to files and trace code dependencies.

How this skill works

The skill exposes three main reference artifacts: a project-structure map with line counts, a flattened files document that contains every file content, and a short summary with statistics and format notes. To find code, consult project-structure.md for paths and sizes, then open the corresponding section in files.md by searching for the file header. Grep-style keyword searches across files.md let you find usages, error messages, or implementation patterns.

When to use it

• Exploring overall project layout before making changes
• Tracing where a feature or endpoint is implemented
• Reading source for a specific file or module
• Searching for function/variable usages across the codebase
• Debugging an error by locating messages or stack traces in source

Best practices

• Start with references/summary.md to understand conventions and excluded files
• Use project-structure.md line counts to prioritize large, complex files first
• Open files.md sections by searching the exact '## File: <path>' header to get full file content
• Use consistent keywords when grepping to reduce false positives (e.g., full function names or class names)
• Cross-reference imports found in a file to trace dependencies across modules

Example use cases

• Understand how the authentication flow is wired by locating controller, service, and route files in project-structure.md and reading their implementations in files.md
• Investigate a runtime error by searching the error message or thrown class across files.md to find origin and callers
• Locate every usage of a utility function by grepping its name in files.md to identify coupling before refactor
• Estimate effort to modify a component by checking its file size and related module files via project-structure.md
• Audit tech stack and dependencies by consulting tech-stack.md for languages and frameworks used