Make the repo self-onboarding for Claude Code and Codex - #191
Merged
Conversation
The article-writer skill existed only as an untracked skills/ directory on one machine, in a path no agent tool scans. It was never surfaced or read, and a recent article shipped at 3313 words - 3x the longest article in its section - because the style guide sat unread two directories away. - Move skills/altinity-kb-article-writer to .claude/skills/, which Claude Code loads automatically, and commit it. It already carried an agents/openai.yaml, so cross-tool use was the original intent. - AGENTS.md: add a "Start here" table pointing at all five skill files, noting that Codex and other tools do not auto-load them and must read the files directly. Codex reads AGENTS.md, so this is the entry point that works for every tool. - AGENTS.md: add a length budget. Across the 250 articles in content/en the median is ~430 words and 90% are under 1100, but nothing stated a target, so an agent had no anchor. Target under 1000, over 1500 needs a reason (13 of 250 qualify). Adds two items to the final checklist. - CLAUDE.md: thin pointer to AGENTS.md plus the three rules most often broken. Deliberately short to avoid drifting from AGENTS.md. - kb-style-guide.md: add a Length section deferring to AGENTS.md for the authoritative wording. Hugo contentDir is content/en, so CLAUDE.md and .claude/ are not published. Build verified: 328 pages, unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AsB1E5eSBXpaZT4jGzY57L
Contributor
|
I have read the CLA Document and I hereby sign the CLA You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot. |
The existing final checklist is mechanical - frontmatter present, fences tagged, queries version-gated. A draft can pass every box and still be the wrong article, which is what happened with the 3313-word first version of the export-system-logs page. Adds seven review questions in three groups: - Does the reader need this? The four cutting questions, with the specific guidance that being able to explain why the internals behave a certain way is not a reason to put it in the article - that belongs in the PR. - Is it true? Naming the version an example was run on, rather than asserting it was tested. Also notes that reformatting a tested example un-tests it, which came up when the DDL was reflowed during the simplification pass. - Is it enough? Does it solve the problem end-to-end. The last group is called out as the counterweight. Six of the seven questions push toward cutting and only one pushes toward keeping, so applied without it the set will strip an article past useful. Cut derivations, not decisions. Placed in AGENTS.md rather than the skill because the skill is scoped to writing new articles while these apply equally to edits, and because the skill auto-loads for Claude Code only - Codex reads AGENTS.md. The skill's qa-checklist.md points here instead of duplicating. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AsB1E5eSBXpaZT4jGzY57L
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The
altinity-kb-article-writerskill existed only as an untrackedskills/directory on one machine, in a path no agent tool scans. Result: it was never surfaced, its style guide was never read, and #189 shipped a 3313-word article — 3× the longest in its section, against a median of 498 — before @BorisTyshkevich caught it (fixed in #190).The guidance to prevent that was in the repo the whole time. It just wasn't anywhere a tool would look.
Changes
Move
skills/altinity-kb-article-writer→.claude/skills/, and commit it. Claude Code scans~/.claude/skills/and.claude/skills/— not<repo>/skills/. Committing it also means it stops living on a single machine. It already shipped anagents/openai.yaml, so cross-tool use was the original author's intent.AGENTS.md— "Start here" section. A table pointing at all five skill files, stating plainly that Codex and other tools do not auto-load them and must read the files directly. Since Codex readsAGENTS.mdand Claude Code readsCLAUDE.md,AGENTS.mdis the entry point that works for both. It also warns against calibrating style by grepping neighbouring articles — that yields the frontmatter shape and none of the tone or length norms, which is precisely how #189 went wrong.AGENTS.md— length budget. The file already said "prefer dense, operational wording" and "remove empty words", but nothing gave a number, so there was no anchor to check against. Measured across all 250 articles incontent/en:Rule: target under 1000, over 1500 needs a clear reason — only 13 of 250 articles qualify. Plus the diagnosis that matters: when an article runs long it's usually mechanism write-ups, source walkthroughs, stack traces, or evidence tables, all of which belong in the PR description rather than the KB. Two items added to the final checklist.
CLAUDE.md— new, deliberately thin (37 lines). Points atAGENTS.mdas the source of truth and repeats only the three rules most often broken. Kept minimal on purpose so it can't drift fromAGENTS.md.kb-style-guide.md— a Length section that defers toAGENTS.mdfor authoritative wording, so the number lives in one place.Verification
namematches the directory; internalreferences/paths are relative and survive the move; no staleskills/paths remain in the repo.altinity-kb-article-writerappeared in the agent's available-skills list automatically — the exact mechanism that failed to fire at the start of the session that prompted this.contentDiriscontent/en, soCLAUDE.mdand.claude/are not published. Build verified with the CI-pinned 0.128.2: 328 pages, unchanged, and neither path appears in the output.The one judgment call to review
The word thresholds are mine, not yours. 1000 / 1500 is derived from the p75–p90 range of the existing corpus, but it becomes a rule every future contributor is measured against. If you'd rather it were 800/1200, or advisory rather than a rule, say so and I'll adjust — that's the line I'd most expect to change in review.
🤖 Generated with Claude Code
https://claude.ai/code/session_01AsB1E5eSBXpaZT4jGzY57L