Kramme:skill:audit sources
Skill Abildtoft/kramme-cc-workflow/.agents/skills/kramme:skill:audit-sources
Audit one or more skills in this repo against their declared sources of inspiration (official docs, blog posts, library READMEs, papers) to detect upstream changes worth incorporating. On first run for a skill, scan its SKILL.md and references/ to propose a sources manifest. On subsequent runs, fetch each source transiently, compare its normalized hash to the stored baseline hash, and surface concrete additions without retaining the source body. Use when maintaining the repo and you want to refresh skills against their inspirations. Not for editing skills, validating frontmatter, or auditing code dependencies.From its SKILL.md
npx -y skills add Abildtoft/kramme-cc-workflow --skill kramme:skill:audit-sourcesAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.8 KB, as published. Nobody here has run it
Audit Skill Sources
Detect when a skill's sources of inspiration have been updated upstream and surface changes that could be valuable additions to the skill.
This is a local repository-maintenance skill under .agents/skills/. It is intentionally not part of the shipped Claude Code plugin or converter output.
This skill operates in three modes, picked automatically based on per-skill state:
- Bootstrap — no
references/sources.yamlexists yet for the target skill. Propose one from URLs and library names found in the skill's content. - Audit — a manifest exists. Fetch each declared source transiently, normalize it, and compare its hash to the stored baseline hash. On change, ask the model to surface valuable additions against the current
SKILL.md. - Refresh — after an audit, optionally update hashes and
last_reviewed_at.
Fetched source bodies are never repository artifacts. Do not create or commit a references/sources-snapshot/ directory. Retain only source URLs, original provenance notes, review dates, hashes, and paraphrased audit findings.
Phase 1: Parse Arguments
- Read
$ARGUMENTS. Accepted shapes:- Empty → ask the user which skill, glob, or
all. - Exact skill name (e.g.
kramme:code:harden-security) → single target. - Glob (e.g.
kramme:code:*) → expand against every skills directory in the repo. all→ every skill found in the repo.
- Empty → ask the user which skill, glob, or
- Resolve the target list by globbing skill directories under (in order):
.agents/skills/,kramme-cc-workflow/skills/,kramme-connect-workflow/skills/. Skip the.claude/skills/symlink to avoid double-counting. Deduplicate. If the list is empty, stop and report "no skills matched". - If the list has more than 10 skills, confirm with the user before proceeding (audits make network calls and can be slow).
Phase 2: For Each Target Skill
Process targets sequentially, not in parallel — keeps the audit report ordered and avoids rate-limiting upstream sources.
For each target skill, check whether references/sources.yaml exists.
- If missing → run Phase 3 (Bootstrap). After bootstrap, optionally continue to Phase 4 for the same skill.
- If present → skip to Phase 4 (Audit).
Phase 3: Bootstrap
Goal: propose a sources.yaml for a skill that has none yet, then write it after user confirmation.
- Read the schema reference from
references/sources-yaml-schema.md. - Read the bootstrap prompt from
references/bootstrap-prompt.mdand follow it. The prompt instructs the model to:- Read the target skill's
SKILL.mdand every file under itsreferences/. - Extract candidate sources: external URLs, named libraries (for resolution via a docs MCP if present), and named-but-unlinked references ("OWASP Top 10", "Hyrum's Law").
- Distinguish inspiration sources (the skill's content is derived from them) from illustrative references (mentioned but not the basis of the skill). Only inspiration sources go into the manifest.
- Classify each source as
usage: inspirationorusage: copied. Copied entries require a verified compatiblelicense, a skill-relativenoticefile containing the complete required notice, an exactupstream_path, and an immutable upstream commit, revision, release, or version.
- Read the target skill's
- Present the proposed
sources.yamlto the user for review and editing. Ask the user to confirm:- "Accept proposed sources, edit before writing, or skip this skill?"
- On accept, write the file to
<target-skill-dir>/references/sources.yaml. Setlast_reviewed_atto today and leavebaseline_hashempty (Phase 4 will populate it on first fetch). - Log the action in the running audit report (Phase 6).
Phase 4: Audit
Goal: fetch each declared source, decide whether it has changed, and on change ask the model to surface valuable additions.
- Read
references/sources.yamlfor the target skill. - For each source entry:
- Fetch or extract.
- If the entry has
graphql_definitions, require an HTTPSurland runpython3 scripts/extract_graphql_definitions.py --url "<url>" <name>..., passing the listed names in manifest order. The helper fetches the schema inside the local process so the full response never enters model context; capture only its bounded stdout. Treat a fetch error, missing definition, or malformed definition as a source error. Never call the runtime web-fetch tool for this entry and never fall back to snapshotting the full schema. - Otherwise, if
context7_libraryis set, fetch the library docs via the available docs MCP if present (e.g. Context7'sresolve-library-id+query-docs); fall back to a web fetch of the library's canonical docs URL. - Otherwise, fetch the declared
urlvia the runtime's web-fetch tool. On fetch error, record the error in the report and continue to the next source.
- If the entry has
- Normalize and hash. Pipe the fetched or extracted content through
scripts/normalize.py(seereferences/normalization-rules.md). Use--type markdownas the lossless plain-text mode for raw Markdown, GraphQL extraction output, GitHub README files,.mdURLs, docs-MCP markdown output, raw source code, and any other non-HTMLtext/plainresponse; use--type htmlonly for fetched HTML pages. The script writes normalized content to stdout and prints the sha256 hash to stderr. - Compare hashes.
baseline_hashis empty → mark "baseline initialized" in the report. Stage the new hash for Phase 5, but skip the LLM step because this is the first successful review.- Hash matches
baseline_hash→ mark "unchanged" in the report. Skip the LLM step. - Hash differs from a non-empty
baseline_hash→ continue.
- LLM compare (only on change). Read the comparison prompt from
references/comparison-prompt.md. Provide it with: (a) the freshly fetched normalized content, (b) the currentSKILL.mdof the target skill, and (c) the source rationale. The model returns an original, paraphrased suggestion (or "Nothing actionable.") and must not reproduce source passages. - Stage the new hash in memory. Do not write the normalized source body to the repository or a durable cache.
- Fetch or extract.
- Append the per-source results to the running audit report.
Phase 5: Persist Baselines
After all targets are processed, ask the user once:
"Update hash baselines for the N sources that changed? This will update
baseline_hashandlast_reviewed_atin eachsources.yaml. It will not retain fetched source bodies, commit, or stage files."
On accept:
- Update the
baseline_hashandlast_reviewed_atfields for each changed source in itssources.yaml. - Discard fetched and normalized source bodies after the report is complete. Do not write them under a skill,
.context/, or another durable cache. - Do not commit. Leave staging to the user.
On decline, do not modify any files. The audit report still records what changed.
Phase 6: Write the Report
- Read the report template from
references/report-template.md. - Fill in:
- Summary table — one row per skill: total sources, changed, unchanged, errors, bootstrapped.
- Per-skill sections — for each skill: changed sources with the model's original paraphrased suggestion and relevant source section/link; unchanged sources as a one-line list; errors with the underlying message. Do not include copied source excerpts.
- Write the report to
.context/skill-source-audit-<YYYYMMDD-HHMM>.mdin the workspace root. Create.context/if missing. - Print the path to the user.
Phase 7: Hand-off
Print a short summary:
Audited N skills (B bootstrapped, C with changed sources, E errors).
Report: .context/skill-source-audit-<timestamp>.md
Baselines: <updated|unchanged>
Suggest next steps in plain English: "Open the report and decide which suggestions to fold into each SKILL.md. You can hand the report back to Claude in a follow-up to apply specific suggestions."
Failure modes
- Web fetch blocked / 4xx / 5xx → record the error against that source and continue. Do not retry more than once.
- Docs MCP cannot resolve the library → fall back to web fetch of the canonical docs URL if known; otherwise record and continue.
normalize.pyfails on input → record raw fetched length and a hash of the raw content so a re-run can detect change at all; flag the source as "needs manual review" in the report.sources.yamlmalformed → stop processing that skill, log the parse error in the report, continue to the next skill.
Reference
For schema, prompts, normalization rules, and report template, read these resources on demand:
references/sources-yaml-schema.md—sources.yamlschema, usage and license fields, examplesreferences/bootstrap-prompt.md— prompt for proposing a manifest from existing skill contentreferences/comparison-prompt.md— prompt for surfacing valuable additions from changed sourcesreferences/normalization-rules.md— what transient source contentnormalize.pystrips and keeps before hashingreferences/report-template.md— markdown skeleton for the audit reportscripts/normalize.py— HTML/markdown → normalized text + sha256 hash