Skip to content

armelhbobdad/oh-my-skills / .claude/skills/skf-analyze-source

skf-analyze-source

Verified

Discover 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."

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
```
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall