skill-guide

Skill Guidelines Management

Author, extract, merge, simplify, and validate Agent Skills following the Agent Skills spec and authoring best practices.

Spec Constraints

• name: 1-64 chars, lowercase kebab-case; no consecutive/leading/trailing hyphens; not the reserved words anthropic/claude; no XML tags; must match parent dir
• description: 1-1024 chars; imperative "Use when..." + explicit triggers; third person (no "I can..."/"You can...")
• Body: <500 lines / ~5000 tokens; push detail to references/
• Reference files: one level deep under references/, kebab-case filenames
• Optional frontmatter: license (string), compatibility (≤500 chars; declare network/runtime needs), metadata (string→string map), allowed-tools (experimental, space-separated allowlist, e.g. Bash(git:*) Read)
• Progressive-disclosure budget: discovery sees only name+description (~100 tokens), so the description alone decides routing; SKILL.md loads on activation (keep ≤ ~500 lines / 5k tokens); anything needed <~20% of the time belongs in references/, loaded on demand

Core Principles

• Progressive Disclosure: SKILL.md contains essentials; references/* contains depth, loaded on demand
• Project Independence: remove project-specific paths, names, domains; when concrete instance coordinates (hosts, orgs, repos, ids) are genuinely needed, isolate them in one on-demand reference (e.g. a dedicated coordinates.md) so the rest stays reusable and swappable; a general / architectural-pattern skill must also illustrate with a neutral domain (orders, storage, notifications), never the codebase that motivated it: map real concepts onto the neutral example, see references/guideline-skills.md
• Composable split: one concept has one owner skill; prefer small mix-and-match skills, cross-reference others by name instead of duplicating, and generalize anything not inherently language/API-specific into a general skill that specific skills link to for the "why", see references/composability.md
• Design to coexist: a skill is one capability among many loaded together; use by-name advisory handoffs for concept ownership, capability descriptions for optional runtime selection, and manifest dependencies only when the core workflow requires an exact skill; hard dependencies point upward and stay acyclic, see references/composability.md
• Keep composition explicit and small: route optional skills by installed names and descriptions, reserve manifests for exact hard dependencies, and keep content provenance in SOURCES.md, see references/composability.md
• Routing-first descriptions: the description is the router (discovery sees only name+description); tune the trigger words, and debug mis-routes by asking "which skill did you use?", see references/writing-descriptions.md
• Sources in SOURCES.md: cite provenance only in SOURCES.md; every source maps to the guidance it feeds through **References:** all, an explicit reference-file list, or an existing machine-readable **Used for:** / **Aspects extracted:** mapping (prefer **References:** for new edits), and repository-original material uses **Provenance:**; never name authors, companies, talks, books, or blogs inside SKILL.md or references/* (tool/API/standard names are fine); versioned repository sources pin version + checkout + commit + watched paths, while versioned web-only documentation pins an ordered **Content SHA256:**
• Verify against source: check every command, flag, signature, version, and count against the authoritative tool/API/docs before stating it; distilled facts drift and even a confident review "fix" can be wrong, so confirm against source before applying it
• Credential capability skills: a skill that authenticates to an external service gets a keychain-first auth.md (OS keychain → secret-manager CLI → CI/CD secret → cloud vault; never hardcode), with first-time install / connect / init in a separate onboarding.md
• Treat skills as software: least privilege via allowed-tools, audit untrusted scripts/URLs, never hardcode secrets, see references/security.md
• Bullet Format: - **Rule** - Brief 5-10 word how-to, see [references/<topic>.md](references/<topic>.md)
• Style Consistency: match existing skill patterns in structure and voice
• Add what the agent lacks; omit what it knows: trim to the delta over baseline model knowledge (tier-aware) and verify against the weakest model, see references/optimize.md; no general-knowledge filler
• Defaults over menus: one default, alternatives mentioned briefly
• Deletion-first editing: an editing pass cuts at least as much as it adds; if a change grows a file, say what it replaces or bump the file's recorded budget in the same change
• No new nouns: reuse the vocabulary the catalog already owns; a new term of art needs a defining file and an entry in the vocabulary manifest, or it is a synonym and should be deleted
• Anchor to an artifact: every instruction must pass "could an agent do this, and could you verify it did?"; an instruction naming no checkable output is advice, not a skill
• Procedures over declarations: teach the approach/steps, not a one-off answer
• Evals before docs: build trigger/output evals for the gap first, then write the minimum to pass them; iterate observe→revise, see references/evaluating-triggers.md, references/evaluating-outputs.md