cyber-skills 0.0.0

package/skills/configure-awesome-sources/scripts/configure-awesome-sources.mts

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+type SourceClass = 'local-private' | 'repo-shared' | 'global-user'
+
+interface SourceRef {
+	repo: string
+	path: string
+}
+
+interface SourceConfigFile {
+	version: 1
+	sources?: SourceRef[]
+	disabled_sources?: SourceRef[]
+}
+
+function normalizeRepo(repo: string): string {
+	return repo
+		.trim()
+		.replace(/^https?:\/\/github\.com\//, '')
+		.replace(/\.git$/, '')
+		.replace(/^\/+|\/+$/g, '')
+}
+
+function normalizePath(filePath: string): string {
+	return filePath.trim().replace(/^\/+/, '') || 'awesome-skills.json'
+}
+
+function sourceKey(source: SourceRef): string {
+	return `${normalizeRepo(source.repo)}::${normalizePath(source.path)}`
+}
+
+function getLayerFilePath(cwd: string, sourceClass: SourceClass): string {
+	switch (sourceClass) {
+		case 'local-private':
+			return path.join(cwd, '.agents', 'awesome-skill-sources.local.json')
+		case 'repo-shared':
+			return path.join(cwd, '.agents', 'awesome-skill-sources.json')
+		case 'global-user':
+			return path.join(os.homedir(), '.agents', 'awesome-skill-sources.json')
+	}
+}
+
+function parseRepositoryFromPackage(cwd: string): string | null {
+	const manifestPath = path.join(cwd, 'package.json')
+	if (!fs.existsSync(manifestPath)) return null
+	const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as { repository?: { url?: string } | string }
+	const repoUrl = typeof manifest.repository === 'string' ? manifest.repository : manifest.repository?.url
+	if (!repoUrl) return null
+	const match = repoUrl.match(/github\.com[:/](.+?)(?:\.git)?$/)
+	return match ? normalizeRepo(match[1]) : null
+}
+
+function loadSourceConfigFile(filePath: string): SourceConfigFile {
+	if (!fs.existsSync(filePath)) return { version: 1, sources: [], disabled_sources: [] }
+	return JSON.parse(fs.readFileSync(filePath, 'utf8')) as SourceConfigFile
+}
+
+function saveSourceConfigFile(filePath: string, config: SourceConfigFile): void {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true })
+	fs.writeFileSync(
+		filePath,
+		`${JSON.stringify(
+			{
+				version: 1,
+				...(config.sources && config.sources.length > 0 ? { sources: config.sources } : {}),
+				...(config.disabled_sources && config.disabled_sources.length > 0
+					? { disabled_sources: config.disabled_sources }
+					: {}),
+			},
+			null,
+			2,
+		)}\n`,
+	)
+}
+
+function parseArgs(argv: string[]) {
+	const args = argv.slice(2)
+	const command = args[0]
+	const layerValue = readFlag(args, '--layer')
+	const repo = readFlag(args, '--repo')
+	const filePath = normalizePath(readFlag(args, '--path') ?? 'awesome-skills.json')
+	return { command, layerValue, repo, filePath }
+}
+
+function readFlag(args: string[], flag: string): string | undefined {
+	const index = args.indexOf(flag)
+	return index === -1 ? undefined : args[index + 1]
+}
+
+function resolveLayer(value: string | undefined): SourceClass {
+	switch (value) {
+		case 'local':
+		case 'local-private':
+			return 'local-private'
+		case 'repo':
+		case 'repo-shared':
+			return 'repo-shared'
+		case 'global':
+		case 'global-user':
+			return 'global-user'
+		default:
+			throw new Error('Expected --layer local|repo|global')
+	}
+}
+
+function mutateRefs(refs: SourceRef[], predicate: (ref: SourceRef) => boolean, next?: SourceRef): SourceRef[] {
+	const kept = refs.filter((ref) => !predicate(ref))
+	if (next) kept.push(next)
+	return kept.sort((a, b) => sourceKey(a).localeCompare(sourceKey(b)))
+}
+
+function getCurrentSourceSet(config: SourceConfigFile): Set<string> {
+	return new Set([...(config.sources ?? []), ...(config.disabled_sources ?? [])].map(sourceKey))
+}
+
+function getLowerLayerSources(cwd: string, layer: SourceClass): Set<string> {
+	const all: SourceClass[] = ['global-user', 'repo-shared', 'local-private']
+	const index = all.indexOf(layer)
+	const refs = new Set<string>()
+	for (const item of all.slice(0, index)) {
+		const config = loadSourceConfigFile(getLayerFilePath(cwd, item))
+		for (const ref of config.sources ?? []) refs.add(sourceKey(ref))
+	}
+	return refs
+}
+
+function getResolvedSources(cwd: string): Array<SourceRef & { sourceClass: SourceClass | 'default' }> {
+	const layers: Array<{ sourceClass: SourceClass; path: string }> = [
+		{ sourceClass: 'local-private', path: getLayerFilePath(cwd, 'local-private') },
+		{ sourceClass: 'repo-shared', path: getLayerFilePath(cwd, 'repo-shared') },
+		{ sourceClass: 'global-user', path: getLayerFilePath(cwd, 'global-user') },
+	]
+	const disabled = new Set<string>()
+	const kept = new Map<string, SourceRef & { sourceClass: SourceClass | 'default' }>()
+
+	for (const layer of layers) {
+		const config = loadSourceConfigFile(layer.path)
+		for (const ref of config.disabled_sources ?? []) disabled.add(sourceKey(ref))
+	}
+
+	const currentRepo = parseRepositoryFromPackage(cwd)
+	if (currentRepo) {
+		const ref = { repo: currentRepo, path: 'awesome-skills.json' }
+		const key = sourceKey(ref)
+		if (!disabled.has(key) && fs.existsSync(path.join(cwd, ref.path))) {
+			kept.set(key, { ...ref, sourceClass: 'default' })
+		}
+	}
+
+	for (const layer of layers.reverse()) {
+		const config = loadSourceConfigFile(layer.path)
+		for (const ref of config.sources ?? []) {
+			const key = sourceKey(ref)
+			if (disabled.has(key) || kept.has(key)) continue
+			kept.set(key, { ...ref, sourceClass: layer.sourceClass })
+		}
+	}
+
+	return Array.from(kept.values())
+}
+
+function printUsage(): void {
+	console.log('Usage:')
+	console.log('  tsx skills/configure-awesome-sources/scripts/configure-awesome-sources.mts list')
+	console.log(
+		'  tsx skills/configure-awesome-sources/scripts/configure-awesome-sources.mts add --layer local|repo|global --repo owner/name [--path awesome-skills.json]',
+	)
+	console.log(
+		'  tsx skills/configure-awesome-sources/scripts/configure-awesome-sources.mts remove --layer local|repo|global --repo owner/name [--path awesome-skills.json]',
+	)
+	console.log(
+		'  tsx skills/configure-awesome-sources/scripts/configure-awesome-sources.mts disable --layer local|repo|global --repo owner/name [--path awesome-skills.json]',
+	)
+	console.log(
+		'  tsx skills/configure-awesome-sources/scripts/configure-awesome-sources.mts enable --layer local|repo|global --repo owner/name [--path awesome-skills.json]',
+	)
+}
+
+const cwd = process.cwd()
+const { command, layerValue, repo, filePath } = parseArgs(process.argv)
+
+if (!command || command === '--help' || command === 'help') {
+	printUsage()
+	process.exit(0)
+}
+
+if (command === 'list') {
+	const sources = getResolvedSources(cwd)
+	if (sources.length === 0) {
+		console.log('No awesome sources configured.')
+		process.exit(0)
+	}
+	console.log('Effective awesome sources:')
+	for (const source of sources) console.log(`- ${source.repo} (${source.path}) [${source.sourceClass}]`)
+	process.exit(0)
+}
+
+const layer = resolveLayer(layerValue)
+if (!repo) throw new Error('Expected --repo owner/name')
+const ref = { repo: normalizeRepo(repo), path: filePath }
+const configPath = getLayerFilePath(cwd, layer)
+const config = loadSourceConfigFile(configPath)
+const predicate = (item: SourceRef) => sourceKey(item) === sourceKey(ref)
+const currentRefs = getCurrentSourceSet(config)
+const inheritedSources = getLowerLayerSources(cwd, layer)
+
+switch (command) {
+	case 'add':
+		config.sources = mutateRefs(config.sources ?? [], predicate, ref)
+		config.disabled_sources = mutateRefs(config.disabled_sources ?? [], predicate)
+		saveSourceConfigFile(configPath, config)
+		console.log(`Added ${ref.repo} (${ref.path}) to ${configPath}`)
+		break
+	case 'remove':
+		config.sources = mutateRefs(config.sources ?? [], predicate)
+		config.disabled_sources = mutateRefs(config.disabled_sources ?? [], predicate)
+		saveSourceConfigFile(configPath, config)
+		console.log(`Removed ${ref.repo} (${ref.path}) from ${configPath}`)
+		break
+	case 'disable':
+		config.sources = mutateRefs(config.sources ?? [], predicate)
+		config.disabled_sources = mutateRefs(config.disabled_sources ?? [], predicate, ref)
+		saveSourceConfigFile(configPath, config)
+		console.log(`Disabled ${ref.repo} (${ref.path}) in ${configPath}`)
+		break
+	case 'enable':
+		config.disabled_sources = mutateRefs(config.disabled_sources ?? [], predicate)
+		if (!currentRefs.has(sourceKey(ref)) && !inheritedSources.has(sourceKey(ref))) {
+			config.sources = mutateRefs(config.sources ?? [], predicate, ref)
+			console.log(`Enabled ${ref.repo} (${ref.path}) in ${configPath} and added it as a direct source.`)
+		} else {
+			config.sources = mutateRefs(config.sources ?? [], predicate)
+			console.log(`Enabled ${ref.repo} (${ref.path}) in ${configPath}.`)
+		}
+		saveSourceConfigFile(configPath, config)
+		break
+	default:
+		printUsage()
+		process.exit(1)
+}
+
+const currentRepo = parseRepositoryFromPackage(cwd)
+if (
+	currentRepo &&
+	sourceKey(ref) === sourceKey({ repo: currentRepo, path: 'awesome-skills.json' }) &&
+	command === 'disable'
+) {
+	console.log('Note: this disables the built-in default source for the current repo as well.')
+}

package/skills/create-skill/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: create-skill
+description: Use this skill when the user asks to create a new agent skill. Creates the skill directory under ~/.agents/skills/ and links it into all detected agents so they can pick it up.
+---
+
+# Create Skill
+
+When the user asks to create a new skill, follow this convention.
+
+## Directory structure
+
+Skills live in `~/.agents/skills/<name>/` and are linked into each agent's skills directory:
+
+```
+~/.agents/skills/
+  <name>/
+    SKILL.md        ← source of truth, edit this
+~/.claude/skills/
+  <name>            ← symlink → ~/.agents/skills/<name>  (Claude Code)
+# ...and equivalent paths for other detected agents
+```
+
+## Steps
+
+### 1. Create the skill
+
+Check whether `npx skills` is available:
+
+```bash
+npx skills --version 2>/dev/null
+```
+
+**If available**, use it to scaffold the skill:
+
+```bash
+npx skills init <name> --dir ~/.agents/skills
+```
+
+This creates `~/.agents/skills/<name>/SKILL.md` with a starter template. Edit that file to fill in the real content.
+
+**If not available**, create manually:
+
+```bash
+mkdir -p ~/.agents/skills/<name>
+```
+
+Then write `~/.agents/skills/<name>/SKILL.md` using this template:
+
+```markdown
+---
+name: <name>
+description: Use this skill when <trigger condition>. <One-line summary of what it does.>
+---
+
+# <Name>
+
+## When to use
+
+<Describe when this skill should be used.>
+
+## Instructions
+
+1. First step
+2. Second step
+```
+
+### 2. Audit the skill
+
+Run automated checks first:
+
+```bash
+npx tsx .agents/skills/audit-skill/scripts/validate-skills.mts --path ~/.agents/skills/<name>
+```
+
+Fix any CRITICAL findings before proceeding.
+
+Then invoke the **audit-skill** agent skill for full review (Q6–Q12, E3–E8, P1–P3). Do not continue to step 3 if any CRITICAL findings remain.
+
+### 3. Link to agents
+
+**If `npx skills` is available:**
+
+```bash
+npx skills add ~/.agents/skills/<name>
+```
+
+This detects all installed agents and prompts the user to choose which ones to link. It handles the correct path for each agent (Claude Code, Cursor, Codex, OpenCode, etc.).
+
+**Known issue:** `npx skills` has a bug where it may not create `~/.claude/skills/` if the directory doesn't exist yet. After linking, verify:
+
+```bash
+ls ~/.claude/skills/<name>
+```
+
+If missing, fall back to the manual step below.
+
+**If `npx skills` is not available, or the symlink is missing after the above:**
+
+```bash
+ln -sf ~/.agents/skills/<name> ~/.claude/skills/<name>
+```
+
+Adjust the target path for other agents as needed (e.g., `~/.cursor/skills/`, `~/.opencode/skills/`).
+
+## What makes a good skill
+
+- **Decisions over documentation.** Encode what to decide and how — don't repeat reference material the model already knows.
+- **Narrow and composable.** One workflow per skill. Skills can be triggered by situation (user-facing) or called by other skills (sub-skills). Sub-skills have no situational trigger — their `description` should say "Internal skill: called by X" to avoid accidental activation. Neither type should be loaded as ambient context.
+- **No baked-in opinions.** Detect the user's setup (package manager, monorepo shape, tooling) at runtime rather than assuming a specific stack.
+
+## Skill script output discipline
+
+If the skill includes a `scripts/` directory, apply these rules so agents do not confuse human output with machine results:
+
+- **Stdout is the machine contract** — one JSON value or silence; no prose, tables, or progress in default mode
+- **Files hold durable state** — agents read artifacts by path named in stdout JSON or SKILL.md
+- **Stderr is human/diagnostic** — use `console.warn` / `console.error`; gate tables and progress behind `--verbose`
+- **Skills present; scripts record** — SKILL.md tells the agent what file or field to read; the agent summarizes for the user
+- **Autonomous runs** — document `--yes` or equivalent non-interactive flags; never put prompts on stdout
+- **Implementation** — use `process.stdout.write(JSON.stringify(result) + '\n')` for contract output; never `console.log`
+
+## Notes
+
+- `~/.agents/skills/` is the source of truth — commit or back up this directory.
+- Agent skills directories (e.g. `~/.claude/skills/`) only contain symlinks; never edit files there directly.
+- The `description` frontmatter field is what agents read to decide when to activate the skill — make it specific and include "Use this skill when" trigger language. For sub-skills, prefix with "Internal skill:" to prevent unintended activation.

package/skills/find-awesome-skill/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: find-awesome-skill
+description: Use this skill when looking for curated skill recommendations from awesome lists, with exact install commands.
+---
+
+# Find Awesome Skill
+
+Search the user's configured awesome skill sources, merge duplicates, and return concise recommendations with install commands.
+
+## Source discovery
+
+Awesome sources are loaded from these layers, in this order:
+
+1. `.agents/awesome-skill-sources.local.json`
+2. `.agents/awesome-skill-sources.json`
+3. `~/.agents/awesome-skill-sources.json`
+4. The current repo's own `awesome-skills.json` as the default source unless explicitly disabled
+
+Duplicate sources are deduped by `repo + path`.
+
+## Search flow
+
+1. Run the bundled finder:
+
+```bash
+npx tsx skills/find-awesome-skill/scripts/find-awesome-skill.mts "<query>"
+```
+
+For machine-readable output:
+
+```bash
+npx tsx skills/find-awesome-skill/scripts/find-awesome-skill.mts "<query>" --json
+```
+
+2. Load configured awesome sources from the three config layers plus the default source.
+3. Merge duplicate repo or skill entries across sources.
+4. Rank matches by:
+   - exact name match
+   - summary match
+   - tag match
+   - corroboration count
+   - source class preference
+5. Return concise results with:
+   - repo or repo+skill identity
+   - why it matched
+   - primary `why_recommended`
+   - whether other sources also recommended it
+   - exact `npx skills add ...` install command
+
+## Guidance
+
+- Exact name matches should be treated as the strongest signal.
+- Tag and summary matches matter next.
+- Corroboration across multiple awesome sources should increase confidence but should not hide why a result matched.
+- If no results match, say so directly and suggest adding or configuring more awesome sources.