skill3: Instructions file for Claude Code

Skill3 — agent briefing

Java 25 CLI that relearns a technical skill for an AI agent: it discovers documentation, scores it for authority and freshness against a target model's knowledge cutoff, synthesizes an Agent Skills SKILL.md with an LLM, and vets both the input corpus and the output skill with NVIDIA SkillSpector.

The two invariants everything else serves

1. A skill is a post-cutoff delta, not a primer. The target model already knows the topic up to its cutoff; the pipeline gathers only what changed after it. Re-explaining known fundamentals wastes the whole mechanism.
2. Discovery is topic-agnostic. The model plans the searches. There is no per-topic logic anywhere, and adding some — a hardcoded query suffix, a per-skill branch — is the most common way to break this project without failing a test.

Where things are

I need…	Read
What it does, flag by flag	docs/USAGE.md
Install, keys, build	docs/INSTALL.md
How it is structured, and why	docs/ARCHITECTURE.md
The full behavioural spec	docs/SPEC.md
Build gates, releases, guardrails	docs/DEVELOPMENT.md
Generated structure diagrams	docs/diagrams/
Roadmap	docs/PLAN.md

Working on it

./gradlew build          # compile + test + Error Prone, PMD, SpotBugs, ArchUnit, JaCoCo gate
./gradlew test           # tests only
./gradlew diagrams       # regenerate docs/diagrams/*.svg from the source
./gradlew run --args="learn --help"

The build runs on a Gradle-provisioned JDK 25 toolchain, so it does not depend on JAVA_HOME. Coverage is gated at 75% instruction / 65% branch.

Things that will bite you

• Never hand-edit between <!-- VIBETAGS-START --> and <!-- VIBETAGS-END --> in this file, llms.txt or llms-full.txt. Every compile rewrites that region from the @AI* annotations in the Java source. Text outside the markers — including everything above — survives. To change a guardrail, change the annotation.
• The guardrails below are the safety tier only. Per-element detail lives in .claude/rules/ and loads when you open a matching source file.
• Layering is enforced, not suggested. An ArchUnit test asserts that model depends on nothing internal, that only Skill3App touches cli, and that the sub-packages stay acyclic. A convenient import in model fails the build.
• Untrusted data has a defined path. Scraped pages and --input-file content are secret-redacted and scanned before synthesis, fenced as DATA in the prompt, and the output is scanned again. Do not add a shortcut that reaches the model earlier.
• Absence of findings is never asserted. When SkillSpector is unavailable the scans are skipped and nothing is gated — "not scanned" must never be reported as "clean".