Skip to content

CLAUDE.md

Latest commit

 

History

History
140 lines (123 loc) · 9.08 KB

CLAUDE.md

File metadata and controls

140 lines (123 loc) · 9.08 KB
Raw

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

Generated guardrails

Everything below is regenerated from source annotations on every compile.

<project_guardrails> <pii_guardrails> LLM provider API key — never log, echo, or include in errors/fixtures Brave Search subscription token — never log, echo, or include in errors/fixtures </pii_guardrails>

Never include runtime values of elements listed in in logs, console output, external API calls, test fixtures, mock data, or code suggestions. Treat their values as strictly confidential. High Deterministically guarantees SKILL.md spec compliance; model output is never trusted. Changes risk emitting invalid frontmatter — keep the parsing and frontmatter synthesis covered by SkillMdPostProcessorTest. High Accuracy gate that re-grounds claims against the sources. Only worthwhile with a capable model — a weak model rewrites rather than grounds. Keep the prompt strict about supported-claims-only and announced-vs-shipped.

Elements listed in <core_elements> are well-tested core components. Make changes with extreme caution and verify comprehensive test coverage before proposing modifications. <security_elements> Anthropic API credential handling and hosted-provider network egress LLM provider credential resolution and model selection outbound LLM-provider credential (Bearer token) handling output sanitization: reserved-word stripping must never be weakened external-API credential handling and the only network egress with a secret token forwards the Brave subscription token to the search client; must not log it outbound page fetch egress for partly-untrusted URLs; SSRF guard must not be weakened </security_elements>

Elements listed in <security_elements> are security-critical. Never weaken their security properties. Every proposed change must be explicitly reviewed for security impact. <scoped_rules> Detailed per-element guardrails for the elements below live in scoped rule files that load automatically when the matching source file is opened. Consult the referenced file before modifying an element. </scoped_rules>

When you work on any element listed in <scoped_rules>, open its referenced rule file and apply the guardrails there. The rule files are the authoritative source for those elements. </project_guardrails>