cyber-skills 0.0.0

package/skills/init-commit-discipline/scripts/resolve-commit-skill.mts

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Detect installed commit helper skills and recommend defaults.
+ */
+
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export const RECOMMENDED_COMMIT_SKILL = 'commit-work'
+export const RECOMMENDED_INSTALL = 'npx skills add softaworks/agent-toolkit --skill commit-work -g'
+export const BUNDLED_COMMIT_SKILL = 'commit'
+
+const KNOWN_COMMIT_SKILL_NAMES = new Set(['commit-work', 'commit', 'git-commit', 'commit-workflow'])
+
+export interface DetectedCommitSkill {
+	name: string
+	path: string
+}
+
+function skillDirs(root: string): string[] {
+	const home = homedir()
+	return [
+		join(root, '.agents', 'skills'),
+		join(home, '.agents', 'skills'),
+		join(root, '.claude', 'skills'),
+		join(home, '.claude', 'skills'),
+	]
+}
+
+export function detectCommitSkills(root = process.cwd()): DetectedCommitSkill[] {
+	const found = new Map<string, DetectedCommitSkill>()
+
+	for (const base of skillDirs(root)) {
+		if (!existsSync(base)) continue
+		for (const name of KNOWN_COMMIT_SKILL_NAMES) {
+			const skillPath = join(base, name, 'SKILL.md')
+			if (existsSync(skillPath) && !found.has(name)) {
+				found.set(name, { name, path: skillPath })
+			}
+		}
+	}
+
+	return [...found.values()]
+}
+
+export function resolveCommitSkillName(detected: DetectedCommitSkill[], preferred?: string): string | null {
+	if (preferred) return preferred
+	const commitWork = detected.find((s) => s.name === RECOMMENDED_COMMIT_SKILL)
+	if (commitWork) return commitWork.name
+	if (detected.length === 1) return detected[0]!.name
+	return null
+}
+
+if (process.argv[1] === import.meta.filename) {
+	const args = process.argv.slice(2)
+	const rootIdx = args.indexOf('--root')
+	const root = rootIdx !== -1 ? args[rootIdx + 1]! : process.cwd()
+
+	if (args.includes('--recommend')) {
+		process.stdout.write(`${RECOMMENDED_INSTALL}\n`)
+		process.exit(0)
+	}
+
+	const detected = detectCommitSkills(root)
+	const payload = {
+		detected,
+		recommended: RECOMMENDED_COMMIT_SKILL,
+		recommendedInstall: RECOMMENDED_INSTALL,
+		bundledFallback: BUNDLED_COMMIT_SKILL,
+		resolved: resolveCommitSkillName(detected),
+	}
+
+	process.stdout.write(`${JSON.stringify(payload)}\n`)
+	process.exit(detected.length > 0 ? 0 : 1)
+}

package/skills/patch-skill/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: patch-skill
+description: Use this skill when contributing local improvements to an installed skill back to its source repo via PR.
+---
+
+# Patch Skill
+
+When you have improved a skill you installed from another repo, this skill guides you through contributing that improvement back to the source via a pull request.
+
+## When to use
+
+- You modified a skill (global `~/.agents/skills/<name>/` or repo-internal `.agents/skills/<name>/`) and want to send the improvement upstream
+- The skill was installed from a public repo tracked in `skills-lock.json`
+
+Do NOT use for repo-native skills under this repo's `skills/<name>/` — if you're the author here, this repo IS the source.
+
+## Source repository scope (required)
+
+Only update files under the source repo's canonical skills tree:
+
+```text
+<repo-root>/skills/<skill-name>/
+  SKILL.md
+  scripts/          ← include when changed
+  …                 ← any other files in that skill folder
+```
+
+Rules:
+
+- **Always** map upstream paths to `skills/<skill-name>/…`, even when `skills-lock.json` `skillPath` points at `.agents/skills/…` or another layout in the consumer repo.
+- **Never** update `.agents/skills/`, duplicate trees, or paths outside `skills/<skill-name>/` in the source repository.
+- Include every changed file under that skill folder (e.g. `scripts/*.mts`), not only `SKILL.md`.
+- Never include `SKILL.local.md` — local augmentations stay local.
+
+Derive paths:
+
+| Input | Upstream path |
+| --- | --- |
+| Lock key / folder name `audit-skill` | `skills/audit-skill/` |
+| `skillPath`: `.agents/skills/create-skill/SKILL.md` | `skills/create-skill/SKILL.md` |
+| `skillPath`: `skills/fix-security-pr/SKILL.md` | `skills/fix-security-pr/SKILL.md` |
+
+## Steps
+
+### 1. Identify the skill(s) to patch
+
+From context or ask the user. Look up origin in `skills-lock.json` at the consumer repo root:
+
+```bash
+jq '.skills["<skill-name>"]' skills-lock.json
+```
+
+Extract: `source` (`owner/repo`), `skillPath` (for naming only — upstream target is always `skills/<skill-name>/`).
+
+If there is no lock entry, ask for `owner/repo` and the skill folder name.
+
+For multiple related skills (user confirms one PR), repeat file discovery for each `skills/<name>/` directory.
+
+### 2. Find the local skill directory
+
+| Kind | Local directory |
+| --- | --- |
+| Global | `~/.agents/skills/<name>/` |
+| Repo internal | `.agents/skills/<name>/` |
+
+Collect files to contribute (exclude `SKILL.local.md`):
+
+```bash
+find "<local-dir>" -type f ! -name 'SKILL.local.md' | sort
+```
+
+### 3. Diff against source
+
+For each local file, map to `skills/<skill-name>/<relative-path>` and compare to upstream on the default branch.
+
+List upstream skill folder (optional sanity check):
+
+```bash
+gh api "repos/<owner>/<repo>/contents/skills/<skill-name>?ref=<default-branch>" \
+  --jq '.[] | .path'
+# If scripts/ exists, list nested files too:
+gh api "repos/<owner>/<repo>/contents/skills/<skill-name>/scripts?ref=<default-branch>" \
+  --jq '.[]? | .path' 2>/dev/null
+```
+
+Per-file diff:
+
+```bash
+UPSTREAM="skills/<skill-name>/SKILL.md"
+gh api "repos/<owner>/<repo>/contents/${UPSTREAM}" --jq '.content' | base64 -d > /tmp/upstream.md
+diff /tmp/upstream.md "<local-dir>/SKILL.md"
+```
+
+- **No diffs** across all mapped files → nothing to contribute; stop
+- **Any diff** → show unified diffs and get user confirmation before proceeding
+
+### 4. Check write access
+
+```bash
+gh api repos/<owner>/<repo> --jq '{push: .permissions.push, default: .default_branch}'
+```
+
+- `push: true` → branch on `owner/repo`
+- `push: false` → `gh repo fork <owner>/<repo> --clone=false`, then use `<your-username>/<repo>`
+
+### 5. Create branch and push (single commit — Git Data API)
+
+Use the **Git Data API** so all files land in **one commit**. Do not use `PUT /contents/{path}` per file (that creates one commit per file).
+
+Set variables:
+
+```bash
+OWNER=<owner>
+REPO=<repo>
+REPO_FULL="${OWNER}/${REPO}"
+DEFAULT_BRANCH=main   # from step 4
+BRANCH="patch/<skill-name>-<short-slug>"   # or shared slug for multi-skill PR
+MSG="fix(<skill-name>): <description>"
+SKILL_NAME=<skill-name>
+LOCAL_DIR="<absolute-local-skill-dir>"
+```
+
+#### 5a. Create branch ref from default branch tip
+
+```bash
+BASE_SHA=$(gh api "repos/${REPO_FULL}/git/refs/heads/${DEFAULT_BRANCH}" --jq '.object.sha')
+BASE_TREE=$(gh api "repos/${REPO_FULL}/git/commits/${BASE_SHA}" --jq '.tree.sha')
+
+gh api "repos/${REPO_FULL}/git/refs" \
+  --method POST \
+  --field ref="refs/heads/${BRANCH}" \
+  --field sha="${BASE_SHA}"
+```
+
+If the branch already exists, skip creation and set `BASE_SHA` to the branch tip instead (for amending, prefer a fresh branch).
+
+#### 5b. Create blobs and tree entries for each local file
+
+Build a JSON array of tree items. Each local file maps to `skills/${SKILL_NAME}/<relative-path>`.
+
+**Use temp files for `--input`**, not inline `$(jq …)`. Embedding file content in the shell argument hits `ARG_MAX` and fails with errors like `file name too long` on typical `SKILL.md` sizes.
+
+```bash
+TREE_ITEMS='[]'
+while IFS= read -r -d '' file; do
+  rel="${file#${LOCAL_DIR}/}"
+  upstream_path="skills/${SKILL_NAME}/${rel}"
+
+  jq -n --rawfile content "$file" '{content: $content, encoding: "utf-8"}' > /tmp/patch-blob-input.json
+  blob_sha=$(gh api "repos/${REPO_FULL}/git/blobs" \
+    --method POST \
+    --input /tmp/patch-blob-input.json \
+    --jq '.sha')
+
+  TREE_ITEMS=$(jq -n \
+    --argjson items "$TREE_ITEMS" \
+    --arg path "$upstream_path" \
+    --arg sha "$blob_sha" \
+    '$items + [{path: $path, mode: "100644", type: "blob", sha: $sha}]')
+done < <(find "$LOCAL_DIR" -type f ! -name 'SKILL.local.md' -print0)
+```
+
+Repeat the loop for additional skills in the same PR (append to `TREE_ITEMS` with each skill's `SKILL_NAME` and `LOCAL_DIR`).
+
+#### 5c. Create tree, commit, update branch ref
+
+Write tree and commit payloads to temp files as well (large multi-skill `TREE_ITEMS` can also exceed shell limits):
+
+```bash
+jq -n \
+  --arg base "$BASE_TREE" \
+  --argjson tree "$TREE_ITEMS" \
+  '{base_tree: $base, tree: $tree}' > /tmp/patch-tree-input.json
+NEW_TREE=$(gh api "repos/${REPO_FULL}/git/trees" \
+  --method POST \
+  --input /tmp/patch-tree-input.json \
+  --jq '.sha')
+
+jq -n \
+  --arg msg "$MSG" \
+  --arg tree "$NEW_TREE" \
+  --arg parent "$BASE_SHA" \
+  '{message: $msg, tree: $tree, parents: [$parent]}' > /tmp/patch-commit-input.json
+COMMIT_SHA=$(gh api "repos/${REPO_FULL}/git/commits" \
+  --method POST \
+  --input /tmp/patch-commit-input.json \
+  --jq '.sha')
+
+gh api "repos/${REPO_FULL}/git/refs/heads/${BRANCH}" \
+  --method PATCH \
+  --field sha="${COMMIT_SHA}"
+```
+
+Result: exactly **one commit** on the patch branch containing all updated paths under `skills/<skill-name>/`.
+
+### 6. Open PR
+
+```bash
+gh pr create \
+  --repo "${REPO_FULL}" \
+  --base "${DEFAULT_BRANCH}" \
+  --head "${BRANCH}" \
+  --title "fix(<skill-name>): <description>" \
+  --body "$(cat <<'EOF'
+## Summary
+
+<what changed and why — only under `skills/<skill-name>/`>
+
+## Test plan
+
+- [ ] Run audit-skill / `validate-skills.mts` against the updated skill(s)
+- [ ] Confirm no files outside `skills/` were modified
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+### 7. Report
+
+Output the PR URL. After merge, run `npx skills update` in the consumer repo to refresh `skills-lock.json` hashes.
+
+## What NOT to do
+
+- Do not include `SKILL.local.md` content in the PR
+- Do not push without showing diffs and getting user confirmation
+- Do not create a PR if every mapped file is identical to upstream
+- Do not update `.agents/skills/` or any path outside `skills/<skill-name>/` in the source repo
+- Do not use Contents API `PUT` per file (multi-commit noise); use Git Data API (section 5)

package/skills/skillify/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: skillify
+description: Use this skill when generalizing a workflow from the current session into a reusable SKILL.md.
+---
+
+# Skillify
+
+Extracts a repeatable workflow from what was done in the current session and creates a reusable agent skill from it. Different from `create-skill`, which scaffolds from a blank template — this skill analyzes what actually happened and generalizes it.
+
+## When to use
+
+- The user says "skillify this", "make this reusable", "turn what we just did into a skill", or similar
+- A multi-step workflow was completed manually and is worth encoding for future use
+- You want to capture decisions made in a session so an agent can repeat them without re-deriving
+
+## Steps
+
+### 1. Identify the workflow to generalize
+
+From the session history, extract:
+- **Trigger:** What situation prompted this work? What would cause someone to want to do this again?
+- **Decisions:** What choices were made and why? (These are the core of the skill)
+- **Steps:** What was done, in what order?
+- **Inputs:** What did the workflow need to know upfront?
+- **Outputs:** What did it produce or change?
+
+Separate decisions from documentation. The skill should encode what to decide and how — not reference material the model already knows.
+
+### 2. Determine skill kind
+
+| Signal | Kind |
+|---|---|
+| Workflow is personal, not tied to a specific codebase | Global (`~/.agents/skills/<name>/`) |
+| Workflow only makes sense for contributors to this repo | Repo internal (`.agents/skills/<name>/`) |
+| Workflow is meant to be installed by users of this package | Repo public (`skills/<name>/`) |
+
+Ask the user if the context is ambiguous.
+
+### 3. Draft the skill name and description
+
+- **Name:** A short verb-noun or noun phrase that identifies the workflow (e.g., `patch-skill`, `deploy-preview`, `sync-tokens`)
+- **Description:** ≤120 characters; must contain "Use this skill when"; specific enough to discriminate from other skills
+
+Test the description: would an agent activate this skill in the right situation and NOT activate it otherwise?
+
+### 4. Write SKILL.md
+
+Use this structure:
+
+```markdown
+---
+name: <name>
+description: Use this skill when <trigger>. <One-line summary.>
+---
+
+# <Title>
+
+## When to use
+
+<Precise trigger conditions>
+
+## Steps
+
+### 1. <Step title>
+<Decision logic, not documentation>
+
+### 2. <Step title>
+...
+
+## What NOT to do
+
+- <Common mistake or anti-pattern>
+```
+
+Rules:
+- Encode the WHY behind each step (the constraint or decision), not just the WHAT
+- Flag deterministic steps as candidates for script extraction (see below)
+- Keep each step focused on one decision or action
+
+### 5. Flag script-extraction candidates
+
+Mark any step that:
+- Produces the same output given the same input (no judgment needed)
+- Involves text manipulation, file I/O, or structured data processing
+
+Add a TODO comment in the skill body:
+```
+<!-- TODO: extract to scripts/<step>.mts -->
+```
+
+### 6. Validate
+
+Invoke `audit-skill` on the draft. Fix any CRITICAL findings before continuing.
+
+Key checks to watch for:
+- **Q1:** Does the description contain "Use this skill when"?
+- **Q5:** Is the description ≤120 characters?
+- **Q6:** Are there baked-in stack assumptions that should be detected at runtime?
+
+### 7. Place and link
+
+Use `create-skill` conventions:
+
+```bash
+# If npx skills is available:
+npx skills add <path-to-skill>
+
+# Manual fallback:
+ln -sf <path-to-skill> ~/.claude/skills/<name>
+```

package/skills/update-awesome-list/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: update-awesome-list
+description: Use this skill when adding or updating a curated awesome-list entry, including summaries and README sync.
+---
+
+# Update Awesome List
+
+Add or update entries in the current repo's `awesome-skills.json`, then regenerate the README awesome-list section.
+
+## Entry target
+
+When the user gives a repo, do not assume the right recommendation unit. Inspect first, then ask whether they want:
+
+- the whole repo as an entry
+- one or more specific skills as entries
+- a repo entry with highlighted skills
+
+If the repo has many public skills, tell the user the exact count when available. If the count is greater than 12, tell the user it appears to be a broad-catalog repo and recommend adding specific skills, while still allowing:
+
+- repo only
+- repo with highlights
+- specific skills only
+
+Use natural-language narrowing when the user wants help selecting standout skills or highlights.
+
+Inspect the repo with the bundled helper:
+
+```bash
+npx tsx skills/update-awesome-list/scripts/inspect-skills-repo.mts --repo owner/name
+```
+
+Narrow by query when needed:
+
+```bash
+npx tsx skills/update-awesome-list/scripts/inspect-skills-repo.mts --repo owner/name --query "release"
+```
+
+## Editing rules
+
+1. Edit `awesome-skills.json`.
+2. Store repo recommendations under the top-level `repos` object, keyed by normalized repo id (`owner/name`).
+3. Store skill recommendations under the top-level `skills` object, keyed by canonical skill id (`owner/name::skill-name`).
+4. Keep the embedded `repo` and `skill` values consistent with the object key.
+5. Store a neutral `summary` for what the repo or skill does.
+6. Store a separate `why_recommended` note for why the user or agent recommends it.
+7. Keep tags short and lower-kebab-case.
+8. Repo entries may include typed `highlights` using:
+
+```json
+{
+  "type": "skill",
+  "key": "audit-skill",
+  "summary": "Audit SKILL.md structure, quality, and security.",
+  "why_recommended": "Strong review rubric before installing or publishing skills.",
+  "tags": ["audit", "security"]
+}
+```
+
+## Finish
+
+After editing, regenerate the README bounded section so the human-facing list stays in sync with `awesome-skills.json`:
+
+```bash
+npx tsx skills/update-awesome-list/scripts/render-awesome-list.mts
+```

package/skills/update-awesome-list/scripts/inspect-skills-repo.mts

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+interface SkillSummary {
+	directory: string
+	name: string
+	description: string
+}
+
+function normalizeRepo(repo: string): string {
+	return repo
+		.trim()
+		.replace(/^https?:\/\/github\.com\//, '')
+		.replace(/\.git$/, '')
+		.replace(/^\/+|\/+$/g, '')
+}
+
+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 parseFrontmatter(content: string): { name: string; description: string } {
+	const lines = content.split('\n')
+	let frontmatterCount = 0
+	let name = ''
+	let description = ''
+	for (const line of lines) {
+		if (line.trim() === '---') {
+			frontmatterCount += 1
+			if (frontmatterCount === 2) break
+			continue
+		}
+		if (frontmatterCount !== 1) continue
+		const nameMatch = line.match(/^name:\s*(.+)$/)
+		if (nameMatch) name = nameMatch[1].trim().replace(/^["']|["']$/g, '')
+		const descriptionMatch = line.match(/^description:\s*(.+)$/)
+		if (descriptionMatch) description = descriptionMatch[1].trim().replace(/^["']|["']$/g, '')
+	}
+	return { name, description }
+}
+
+async function fetchRepoSkills(repo: string): Promise<SkillSummary[]> {
+	const response = await fetch(`https://api.github.com/repos/${repo}/contents/skills`, {
+		headers: {
+			Accept: 'application/vnd.github+json',
+			'User-Agent': 'cyber-skills-awesome-skills',
+		},
+	})
+	if (!response.ok) throw new Error(`Failed to inspect skills/ in ${repo}: ${response.status} ${response.statusText}`)
+	const entries = (await response.json()) as Array<{ type: string; name: string }>
+	const results: SkillSummary[] = []
+	for (const directory of entries
+		.filter((entry) => entry.type === 'dir')
+		.map((entry) => entry.name)
+		.sort()) {
+		const skillResponse = await fetch(`https://api.github.com/repos/${repo}/contents/skills/${directory}/SKILL.md`, {
+			headers: {
+				Accept: 'application/vnd.github+json',
+				'User-Agent': 'cyber-skills-awesome-skills',
+			},
+		})
+		if (!skillResponse.ok) continue
+		const body = (await skillResponse.json()) as { content?: string; encoding?: string }
+		if (!body.content || body.encoding !== 'base64') continue
+		const fm = parseFrontmatter(Buffer.from(body.content, 'base64').toString('utf8'))
+		results.push({ directory, ...fm })
+	}
+	return results
+}
+
+function readLocalRepoSkills(cwd: string): SkillSummary[] {
+	const skillsDir = path.join(cwd, 'skills')
+	if (!fs.existsSync(skillsDir)) return []
+	return fs
+		.readdirSync(skillsDir, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => {
+			const skillMd = path.join(skillsDir, entry.name, 'SKILL.md')
+			const content = fs.existsSync(skillMd) ? fs.readFileSync(skillMd, 'utf8') : ''
+			const fm = parseFrontmatter(content)
+			return { directory: entry.name, ...fm }
+		})
+		.filter((item) => item.name && item.description)
+		.sort((a, b) => a.directory.localeCompare(b.directory))
+}
+
+const args = process.argv.slice(2)
+const repoIndex = args.indexOf('--repo')
+const queryIndex = args.indexOf('--query')
+const repo = normalizeRepo(repoIndex !== -1 ? args[repoIndex + 1] : '')
+const query = (queryIndex !== -1 ? args[queryIndex + 1] : '').toLowerCase()
+if (!repo) {
+	console.error(
+		'Usage: tsx skills/update-awesome-list/scripts/inspect-skills-repo.mts --repo owner/name [--query term]',
+	)
+	process.exit(1)
+}
+
+const currentRepo = parseRepositoryFromPackage(process.cwd())
+const skills = repo === currentRepo ? readLocalRepoSkills(process.cwd()) : await fetchRepoSkills(repo)
+const filtered = query
+	? skills.filter((skill) => `${skill.directory} ${skill.name} ${skill.description}`.toLowerCase().includes(query))
+	: skills
+console.log(`${repo} has ${skills.length} public skill(s).`)
+for (const skill of filtered) console.log(`- ${skill.directory}: ${skill.description}`)

package/skills/update-awesome-list/scripts/render-awesome-list.mts

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { flattenAwesomeEntries, validateAwesomeList } from '../../find-awesome-skill/scripts/awesome-lib.mts'
+
+interface Highlight {
+	type: string
+	key: string
+	summary: string
+}
+
+interface RepoEntry {
+	type: 'repo'
+	repo: string
+	kind: string
+	trust: 'authored' | 'recommended'
+	summary: string
+	why_recommended: string
+	tags: string[]
+	highlights?: Highlight[]
+}
+
+interface SkillEntry {
+	type: 'skill'
+	repo: string
+	skill: string
+	kind: string
+	trust: 'authored' | 'recommended'
+	summary: string
+	why_recommended: string
+	tags: string[]
+}
+
+type Entry = RepoEntry | SkillEntry
+
+function deriveInstallCommand(entry: Entry): string {
+	return entry.type === 'repo' ? `npx skills add ${entry.repo}` : `npx skills add ${entry.repo} --skill ${entry.skill}`
+}
+
+export function renderAwesomeListMarkdown(entries: Entry[]): string {
+	const sections: string[] = ['## Awesome Skills', '']
+	for (const trust of ['authored', 'recommended'] as const) {
+		const grouped = entries
+			.filter((entry) => entry.trust === trust)
+			.sort(
+				(a, b) =>
+					a.repo.localeCompare(b.repo) ||
+					(a.type === 'skill' ? a.skill : '').localeCompare(b.type === 'skill' ? b.skill : ''),
+			)
+		if (grouped.length === 0) continue
+		sections.push(`### ${trust === 'authored' ? 'Authored' : 'Recommended'}`)
+		sections.push('')
+		for (const entry of grouped) {
+			const title = entry.type === 'repo' ? `\`${entry.repo}\`` : `\`${entry.repo}#${entry.skill}\``
+			sections.push(`- ${title} — ${entry.kind}`)
+			sections.push(`  ${entry.summary}`)
+			sections.push(`  Why recommended: ${entry.why_recommended}`)
+			if (entry.tags.length > 0) sections.push(`  Tags: ${entry.tags.map((tag) => `\`${tag}\``).join(', ')}`)
+			sections.push(`  Install: \`${deriveInstallCommand(entry)}\``)
+			if (entry.type === 'repo' && entry.highlights && entry.highlights.length > 0) {
+				sections.push('  Highlights:')
+				for (const highlight of entry.highlights) {
+					sections.push(`  - \`${highlight.type}:${highlight.key}\` — ${highlight.summary}`)
+				}
+			}
+			sections.push('')
+		}
+	}
+	return sections.join('\n').trimEnd()
+}
+
+function updateMarkedSection(content: string, markerName: string, replacement: string): string {
+	const start = `<!-- ${markerName}:START -->`
+	const end = `<!-- ${markerName}:END -->`
+	if (!content.includes(start) || !content.includes(end))
+		throw new Error(`Missing ${markerName} markers in target file`)
+	return content.replace(new RegExp(`${start}[\\s\\S]*?${end}`, 'm'), `${start}\n${replacement}\n${end}`)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	const cwd = process.cwd()
+	const awesomePath = path.join(cwd, 'awesome-skills.json')
+	const readmePath = path.join(cwd, 'readme.md')
+	const awesome = validateAwesomeList(JSON.parse(fs.readFileSync(awesomePath, 'utf8')), awesomePath)
+	const markdown = renderAwesomeListMarkdown(flattenAwesomeEntries(awesome))
+	const updated = updateMarkedSection(fs.readFileSync(readmePath, 'utf8'), 'AWESOME-SKILLS', markdown)
+
+	fs.writeFileSync(readmePath, updated)
+	console.log(`Updated awesome list section in ${readmePath}`)
+}