Skip to content

armelhbobdad/oh-my-skills / .claude/skills/skf-create-skill

skf-create-skill

Verified

Compile a skill from a brief. Supports --batch for multiple briefs. Use when the user requests to "create a skill" or "compile a skill."

references/extraction-patterns-tracing.md

View on GitHub
# Extraction Patterns: Tracing and File-Level Extraction

This file covers re-export tracing protocols and script/asset file-level extraction patterns. For core tier strategies and AST extraction protocol, see `extraction-patterns.md`.

---

## Re-Export Tracing

After initial AST extraction, some top-level exports may resolve to **module imports** rather than direct function definitions. This is common in Python libraries that use `__init__.py` re-exports for a clean public API.

**Detection heuristic:** For each top-level export from `__init__.py` (or equivalent entry point), check if the import path resolves to a directory (contains `__init__.py`) rather than a `.py` file with a matching `def` or `class`. If the initial AST scan found no function/class definition for a known public export, it is likely a module re-export.

**Tracing protocol:**

1. Read the entry point file (e.g., `{package}/__init__.py`) and extract all `from .X import Y` statements
2. For each import where Y was not found by the initial AST scan:
   - Check if the import path resolves to a directory (e.g., `{package}/api/v1/delete/` exists with `__init__.py`)
   - If directory: read its `__init__.py` to find the actual re-exported symbol
   - **Handle aliases:** Check for `from .module import A as B` patterns in the intermediate `__init__.py`. If the parent imports `B`, trace through to `A` in `.module`. If the parent imports `A` but the `__init__.py` only exports it as `B` (via `from .module import A as B`), match by original name `A` and note the alias
   - Trace the symbol to its definition file and run AST extraction on that file
3. Cite the actual definition location by the tool that found it: `[AST:{definition_file}:L{line}]` (T1, `extraction_method: ast-grep`, and as `ast_node_type` the `kind` its recipe declares in `extraction-patterns.md`, or the kind the ast-grep Patterns table in `extraction-patterns-by-hand.md` gives a `find_code` pattern) when an ast-grep rule matched the definition, or `[SRC:{definition_file}:L{line}]` (T1-low, `extraction_method: source-read`, `ast_node_type: null`) when you read it by eye

**Examples:**

```python
# Module re-export — follow required
from .api.v1.delete import delete    # delete/ is a directory → read delete/__init__.py

# Direct function import — no follow needed
from .api.v1.add.add import add      # add.py exists with def add()

# Aliased re-export — follow through alias
# In cognee/api/v1/visualize/__init__.py:
#   from .start_visualization_server import visualization_server
# In cognee/__init__.py:
#   from .api.v1.visualize import start_visualization_server
# → Match start_visualization_server against both definition names AND alias names
#   in the intermediate __init__.py to resolve the chain
```

**Unresolvable imports:** If the import statement is a star-import (`from .X import *`) or a conditional import (`try`/`except`), the symbol cannot be reliably traced via this protocol. Record it with `[SRC:{package}/__init__.py:L{line}]` (T1-low) and a note: "star/conditional import — manual trace required."

**Scope limit:** Only trace re-exports for symbols listed in the top-level entry point's public API. Do not recursively trace beyond one level of `__init__.py` indirection. If a re-export cannot be resolved after one level, record it with a `[SRC:{package}/__init__.py:L{line}]` citation (T1-low) from the import statement itself.

**Other languages:** JS/TS barrel files (`index.ts` with `export { X } from './module'`) follow the same principle — trace the re-export to the definition file. Rust `pub use` and Go package-level re-exports are less common but follow the same heuristic when encountered.

---

## Script/Asset Extraction Patterns

Scripts and assets are file-level artifacts, not code exports. They follow the **file-copy extraction method** — detected in source, copied with provenance citations.

### Detection Heuristics

**Script directories:** `scripts/`, `bin/`, `tools/`, `cli/`, at any depth. A Python package's folder that has one of these four names (it holds `__init__.py`) is code, not a script folder: a `.py` module in it is a script only with a shebang, a top-level `if __name__ == "__main__":` block (either comparison order, parentheses allowed), or as the package's `__main__.py`.
**Asset directories:** `assets/`, `templates/`, `schemas/`, `configs/`, `examples/`

**Script file signals:**

| Signal                  | Strength | Pattern                                                                                                                                       |
|-------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| Entry point declaration | Strong   | `package.json` `bin` field, Cargo.toml `[[bin]]`, pyproject.toml `[project.scripts]`                                                          |
| Shebang + executable    | Strong   | `#!/bin/bash`, `#!/usr/bin/env python`, `#!/usr/bin/env node`                                                                                 |
| CLI argument parser     | Moderate | `argparse`, `yargs`, `commander`, `cobra`, `clap` imports in file                                                                             |
| Directory convention    | Moderate | File in `scripts/`, `bin/`, `tools/`, `cli/`; in a Python package's folder, only `__main__.py` or a module with a shebang or `__main__` block |
| CI/CD reference         | Moderate | Script referenced in `.github/workflows/*.yml`                                                                                                |

**Asset file signals:**

| Signal           | Strength | Pattern                                             |
|------------------|----------|-----------------------------------------------------|
| JSON Schema      | Strong   | `*.schema.json`, file contains `"$schema"` key      |
| Config template  | Strong   | `*.example`, `*.template.*`, `*.sample` extension   |
| Official example | Moderate | File in `examples/` directory, referenced in README |
| OpenAPI/GraphQL  | Moderate | `openapi.json`, `*.graphql`, `swagger.yaml`         |
| Design tokens    | Weak     | `tokens.json`, `theme.json` in `assets/`            |

### Inclusion Rules

- Only include files the brief's scope takes: a `scope.include` pattern matches them and no `scope.exclude` pattern does (an empty `scope.include` takes the files of the brief's `language` that no exclude matches)
- Exclude binary files (check extension: `.so`, `.dll`, `.jar`, `.wasm`, `.exe`)
- Exclude generated files (`dist/`, `build/`, `.webpack/` output)
- Exclude vendored/third-party files
- Flag files >500 lines for user confirmation (may be too large for skill package)
- If `scripts_intent` is absent from the brief, treat as `"detect"` (auto-detection is the default). If `scripts_intent` is explicitly `"none"`, skip scripts detection. Same rule applies to `assets_intent`.

### Provenance and Hashing

Each extracted file receives:
- Citation: `[SRC:{source_path}:L1]` (T1-low — file verified to exist but content not AST-analyzed)
- Content hash: SHA-256 of file content (for drift detection in audit-skill)
- Extraction method: `"file-copy"` (distinct from `"ast-grep"` and `"source-read"`, the values code exports carry)

### Inventory Structure

**Script inventory entry:**
- `name`: filename (e.g., `validate-config.sh`)
- `source_file`: path relative to source root
- `purpose`: extracted from file header comments or README reference (if none found, use filename)
- `language`: detected from extension or shebang
- `content_hash`: SHA-256
- `confidence`: T1-low

**Asset inventory entry:**
- `name`: filename (e.g., `config-schema.json`)
- `source_file`: path relative to source root
- `purpose`: extracted from file header or schema `title`/`description` field
- `type`: `template`, `schema`, `config`, `example`
- `content_hash`: SHA-256
- `confidence`: T1-low
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall