armelhbobdad/oh-my-skills / .claude/skills/skf-analyze-source
skf-analyze-source
VerifiedDiscover what to skill in a large repo and produce recommended skill briefs. Use when the user requests to "analyze source for skills" or "discover skill opportunities."
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.1 KB |
| assets/skill-brief-schema.md | markdown | 13.6 KB |
| customize.toml | config | 3.0 KB |
| references/auto-docs-only.md | markdown | 8.6 KB |
| references/continue.md | markdown | 2.0 KB |
| references/discover-additional-source.md | markdown | 11.0 KB |
| references/generate-briefs.md | markdown | 19.2 KB |
| references/headless-contract.md | markdown | 10.0 KB |
| references/health-check.md | markdown | 804 B |
| references/identify-units.md | markdown | 15.0 KB |
| references/init.md | markdown | 14.4 KB |
| references/map-and-detect.md | markdown | 16.4 KB |
| references/map-unit-exports.md | markdown | 6.2 KB |
| references/recommend.md | markdown | 9.0 KB |
| references/scan-project.md | markdown | 8.2 KB |
| references/scan-root.md | markdown | 3.1 KB |
| references/step-auto-scope-coexistence.md | markdown | 3.6 KB |
| references/step-auto-scope-corpora.md | markdown | 4.3 KB |
| references/step-auto-scope-split.md | markdown | 6.2 KB |
| references/step-auto-scope.md | markdown | 34.3 KB |
| references/step-shape-detect.md | markdown | 7.7 KB |
| references/unit-detection-heuristics.md | markdown | 11.8 KB |
| templates/analysis-report-template.md | markdown | 583 B |
assets/skill-brief-schema.md
View on GitHub# Skill Brief Schema
## Purpose
Defines the output contract for skill-brief.yaml files generated by analyze-source. Each generated brief must conform to this schema to be consumable by brief-skill and create-skill downstream workflows.
## Required Fields
| Field | Type | Constraint | Description |
|-------------|--------|--------------------------------------------------|-----------------------------------------------------------------------------|
| name | string | kebab-case `[a-z0-9-]+` | Unique skill identifier |
| version | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | Auto-detect from source (see Version Detection below), fall back to `1.0.0`. **Side effect on remote sources:** `skf-create-skill` treats `version` as an **implicit** `target_version` hint when `target_version` itself is absent — it will try to resolve `{version}` or `v{version}` to a git tag before cloning and fall back to HEAD with a warning if no tag matches. See `skf-create-skill/references/source-resolution-protocols.md` → "Implicit Tag Resolution". |
| source_repo | string | GitHub URL or local path | Repository or project root (optional when `source_type: "docs-only"`) |
| language | string | Recognized language | Primary programming language |
| scope | object | See Scope Object below | Boundary definition |
| description | string | 1-3 sentences | What the skill covers. Must contain a literal `Use when` clause — validators test for that exact phrase. |
| forge_tier | string | `Quick` / `Forge` / `Forge+` / `Deep` | Inherited from forge-tier.yaml (Title Case) |
| created | string | ISO date `YYYY-MM-DD` | Generation date |
| created_by | string | user_name from config | Who generated the brief |
## Optional Fields
| Field | Type | Constraint | Description |
|--------------------|--------|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| source_type | string | `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
| doc_urls | array | `{url, label, source?}` objects | Documentation URLs for T3 content. Required when `source_type: "docs-only"`. Optional `source` provenance enum: `language-registry` (registry-guaranteed corpus) \| `readme-detection` \| `homepage` \| `pages-api` \| `docs-folder` |
| `scripts_intent` | string | `detect` / `none` / free-text | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
| `assets_intent` | string | `detect` / `none` / free-text | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/"). |
| `target_version` | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable. |
| `target_ref` | string | Git ref (tag or branch) | Optional. Explicit git ref used verbatim as the resolved `source_ref`, bypassing version-to-tag matching. Escape hatch for monorepo crate tags whose prefix differs from the skill name (e.g. tag `livekit/v0.7.42` for skill `livekit-rust`). Remote sources only. Mutually exclusive with `constituent_refs`. |
| `constituent_refs` | object | map of path→ref strings | Optional. Per-constituent git ref overrides for composite (multi-repo or multi-ref) sources. Keys must match entries in the analyze-source `project_paths` array. When absent, a single `target_ref` (or auto-detected ref) applies to all paths. Mutually exclusive with `target_ref`. |
| `source_authority` | string | `official` / `community` / `internal` | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`. |
| `source_ref` | string | Git ref (tag/branch/HEAD) | Resolved git ref used for source access. Set automatically during tag resolution — do not set manually. |
| `scope.tier_a_include` | array | Glob patterns (min 1, non-empty) | Optional narrower tier-A include list for a curated-subset skill: stratified monorepo packages, single-crate `specific-modules` scopes, and multi-entry exports-map packages. When present, `skf-test-skill` re-derives the coverage denominator from this list instead of the coarse `scope.include`. **With it, the denominator deflation guard measures the stored `stats.effective_denominator` against this list's set, in either direction, instead of against the coarse `scope.include` union**, so supply it only when it genuinely narrows the surface, never as an empty list, and never as a way to widen. See `skf-test-skill/references/source-access-protocol.md`. |
| `scope.registry_path` | string | Path from the source root (non-empty) | Optional, for `scope.type: "component-library"`. The component registry file. `skf-create-skill` step 3d reads it instead of detecting a registry, and writes it back, with a `demo-and-registry` amendment, when the user confirms a detected registry or gives its path. |
| `scope.ui_variants` | array | `{name, package?}` objects (`name` non-empty) | Optional, for `scope.type: "component-library"`. The design system variants, the first one primary. |
| `scope.demo_patterns` | array | Glob patterns (non-empty strings) | Optional, for `scope.type: "component-library"`. The demo and example files `skf-create-skill` step 3d leaves out. Step 3d reads them instead of detecting demo files, and writes them back, with a `demo-and-registry` amendment per glob, when the user confirms or adjusts the detected ones. |
When `source_type: "docs-only"`:
- `source_repo` becomes optional (set to doc site URL for reference)
- `doc_urls` must have at least one entry
- `source_authority` is forced to `community` (T3 external documentation cannot be `official`)
- All extracted content gets `[EXT:{url}]` citations
## Version Detection
A brief's `detected_version` starts from the manifest scan: it is the `version` that `skf-scan-manifests.py` gives the unit's own manifest (a Cargo `version.workspace = true` already resolved from its workspace), passed to the brief writer as found, null when there is none. The writer keeps a full `X.Y.Z` semver version and falls back to `"1.0.0"` otherwise, with a warning. Look a version up by hand only in two cases, and pass what you find the same way:
- **A `version_dynamic` manifest** (Python, a version computed at build time): `__version__` in the package's `__init__.py` → `_version.py` if it exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
- **A private workspace root that gives none** (JavaScript/TypeScript: the root `package.json` has `"private": true` with `"workspaces"`, or no `"version"`): the `version` the same scan gives a primary workspace package (e.g., `code/core/package.json`, or the first matching `packages/*/package.json`)
Read those files in the scan root. Where it holds only the manifests (step-auto-scope's remote fetch), `git -C "{scan_root}" sparse-checkout add '/<the file>'` brings one in.
The create-skill workflow (extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
**Target version override:** When `target_version` is present in the brief, it takes precedence over auto-detection. Auto-detection still runs for informational purposes (displayed as "Detected version" alongside the user-specified "Target version"), but the `target_version` value is used as the brief's `version` field. This is particularly useful for docs-only skills (where no package manifest exists) and when the user wants to compile a skill for a specific older version.
**Pre-release handling:** If the detected version contains a pre-release tag (e.g., `1.0.0-beta.0`, `2.0.0-rc.1`), preserve it as-is. Pre-release tags are valid semver and must not be stripped. When comparing versions during reconciliation, use semver-aware comparison that respects pre-release ordering.
## Scope Object
```yaml
scope:
type: full-library | specific-modules | public-api | component-library | reference-app | docs-only
include:
- 'src/**/*.ts' # At least one required
exclude:
- 'src/**/*.test.ts' # Optional
# Optional: narrower tier-A include list for stratified-scope monorepos
# and reference-app pattern surfaces (refined later by skf-brief-skill)
# tier_a_include:
# - 'code/core/src/manager-api/**'
notes: 'Optional rationale for scope decision'
# Additional fields when scope.type is "component-library":
# registry_path: "path/to/registry.ts" # Optional — auto-detected if omitted
# ui_variants: # Optional — design system variants
# - name: "shadcnui"
# package: "packages/components/react-shadcn"
# demo_patterns: # Optional — auto-detected if omitted
# - "**/demo/**"
# - "**/*.stories.*"
```
### Scope Types
| Type | Use When |
|-------------------|--------------------------------------------------------------------------------------|
| full-library | Entire codebase of a unit |
| specific-modules | Selected components or packages |
| public-api | Only exported interfaces |
| component-library | UI component libraries with registries, props-based APIs, and design system variants |
| reference-app | Whole app whose value is wiring patterns, not public exports (embedded sidecars, CLI demos, integration-pattern demonstrators). Also the home for **language / spec references** — engine- or spec-versioned query languages, grammars, or DSLs (e.g. SurrealQL) whose value is construct idioms, not exports. These have no separate scope type; they ride `reference-app` as a sub-shape (see `skf-create-skill` Language / spec-reference sub-shape) |
| docs-only | When source_type is docs-only — no source code available, all content from doc_urls |
> **Documented vs source language.** The `language` field records the language the skill *documents*. For a language / spec reference this may differ from the source language it is extracted from — e.g. a SurrealQL reference extracted from a Rust engine records `language: surrealql`, not `rust`. Use the documented language and a matching code-fence default (e.g. ` ```surql `) throughout the brief.
## YAML Template
```yaml
name: '{unit-name}'
version: '{detected-version or 1.0.0}'
source_type: 'source'
source_repo: '{project_path}'
language: '{detected_language}'
scope:
type: '{detected_scope_type}'
include:
- '{include_pattern}'
exclude:
- '{exclude_pattern}'
notes: '{scope_rationale}'
description: '{1-3 sentence description}'
forge_tier: '{Quick|Forge|Forge+|Deep}'
created: '{current_date}'
created_by: '{user_name}'
```
## Validation Rules
1. **Name uniqueness**: No duplicate names within forge_data_folder
2. **Source accessibility**: source_repo path must exist or be reachable
3. **Language recognized**: Must be a known programming language
4. **Scope type valid**: Must match one of the six defined types (full-library, specific-modules, public-api, component-library, reference-app, docs-only)
5. **Include patterns**: At least one include glob pattern required (exception: `docs-only` scope, where include patterns are optional since no source code is available)
6. **Forge tier match**: Must match value in forge-tier.yaml
7. **Docs-only mode**: When `source_type: "docs-only"`, `doc_urls` required (>= 1), `source_repo` optional
8. Each `doc_urls` entry must have a valid `url` field
## Output Location
Each skill-brief.yaml is written to:
```
{forge_data_folder}/{unit-name}/skill-brief.yaml
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |