Skills
Skills are the intent router below the SOP. The SOP says "load the matching skill"; each skill says what to do for that intent.
| Slice | Covers |
|---|---|
| Review and delivery | reviews, GitHub, PR/issue text, communication |
| Memory and orchestration | durable memory, proof receipts, specs, builds |
| Repo workflow and code intelligence | git/worktrees, semantic tools, clone research, cleanup scanners |
| Elastic and Kibana | domain overlay, Buildkite, labels, ownership, backports, kbn-standup |
| External tools and media | Google Workspace, flights, browser control, images |
Entry contract
Every skill should make four things obvious near the top:
| Field | Purpose |
|---|---|
Use when | routing triggers |
Do not use | boundaries and escalation |
First actions | mandatory first probes or skill loads |
Output | expected deliverable |
The description frontmatter is the primary routing signal. For non-manual skills, include the concise Use when trigger there; the body is only available after routing has already loaded the skill. Body Use when blocks may stay as detailed post-load applicability checks, but no routing trigger should exist only in the body. Keep descriptions specific, include non-obvious trigger words, and state repo/org constraints when a skill is gated.
Source map
| Surface | Path |
|---|---|
| Source | home/exact_dot_agents/exact_skills/ |
| Target | ~/.agents/skills/ |
| Entrypoint | SKILL.md in each skill folder |
| References | optional references/ under the skill folder |
Inventory both readonly_SKILL.md and plain SKILL.md source files; the shared tree currently contains 58 skills. Audit the complete instruction references and incoming callers as well as each entrypoint. Templates, executable helpers, and invocation metadata have separate consumers and must be accounted for without treating them all as instruction prose.
Semantic maintenance
For each skill, identify its distinct triggers, required actions, ordering, exceptions, forbidden effects, and output contract before rewriting. Compress repeated wording only when every affected entry path still reaches the complete rule. Keep independently reachable guards at their point of use.
Record equivalent rewrites separately from corrections to contradictory instructions. A retained skill needs a reason grounded in its contract; it is not a claim that further improvement is impossible. Verify changed decisions with realistic allowed, forbidden, and resume cases, including required references and caller handoffs. File conservation and passing formatting checks do not establish behavioral equivalence.
Loading procedures by branch and phase
Entrypoints retain routing, shared boundaries, and mandatory load triggers. Complete branch procedures live in references; a reference is required before its matching action, not optional background reading. The root records stage, snapshot, evidence, active/terminal packets and unresolved decisions in the existing topic. After compaction, resume that state and load only applicable instructions; do not relaunch terminal work or restart completed verification. A changed candidate makes its affected evidence stale.
| Skill | Conditionally loaded procedure |
|---|---|
k-review | State/change/product criteria within final judgment; authorized fixes before Verify; scoped drafting/delivery |
k-deep-review | Scope/intent intake; risk-selected strong artifact and adversarial questions plus applicable live UI in one final stage |
k-artifact | Generated HTML or live overlay |
k-cli-skills | New skill authoring or installed-version upgrade |
k-communication | Existing-thread reply procedure; shared external-register rules are inline in the entrypoint |
k-diagnosing-bugs | Evidence-driven Understand; authorized fix and cleanup in Produce, with one root-owned final Verify |
k-elastic-domain | GitHub composition or commit attribution |
k-git | Commit/push details before the corresponding operation |
k-kbn-stack | Runtime lifecycle and isolation before start, reuse, stop, or runtime interpretation |
k-kbn-backport | Staging and continuing a conflicted run, in the existing conflict reference |
k-kibana-console-monaco | Typed demo Enter handling |
k-letsfg | Rendered-UI browser fallback |
k-playwriter | Video recording and frame verification |
k-public-sources | Source inspection or multi-source claims |
k-ui-capture | Diff inventory or upload/embedding |
k-walkthrough | Diagram node metadata and example |
k-present-pr instead uses a bundled template helper: the model reads the complete editable HTML while the helper preserves fixed CSS/JS. Authoring and browser verification remain required.
Measure the entrypoint plus every reference actually needed for the path. Splitting alone does not reduce a complete workflow's total: all-branch paths add routing overhead. These changes target irrelevant branch reads and phase reloading; they do not retire rules or establish universal model-behavior equivalence.
Cross-skill hygiene
Concrete file references in shared AI guidance use full deployed paths, including colocated references and helpers. Project-local AGENTS.md may use project-root-relative paths. Use ~/.agents/skills/k-<name>/... for skill files and ~/.local/share/chezmoi/... for repo-only sources. Filename patterns and native include/import syntax retain their own semantics.
- Composition skills sanitize public GitHub text before drafting or posting, load
k-communicationbefore drafting (a draft-only request is still publication text), and strip agentic-session artifacts from the draft. - Slack side effects go through
k-slack(mechanics) with wording fromk-communication; Slack reads need no skill or gate. k-compose-pr,k-compose-issue, and review modes reuse the sharedk-githubGitHub context intake when output depends on existing PR/issue/comment context.- Generic skills own portable mechanics only. If a rule names an org, repo, product, team, label, bot login, CI instance, PR template, live-UI target, ownership policy, or release-note/backport rule, put it in a verified domain overlay or dedicated domain skill.
- Generic skills may dispatch to a domain overlay after verifying the target; they must not inline Elastic/Kibana or other domain defaults.
- GitHub issue worktrees prefer
,gh-worktree issue <owner/repo> <issue_number> --branch <branch-base-name>.
Credits
Four skills are adapted from Matt Pocock's mattpocock/skills (MIT-licensed). Attribution lives here rather than inline in each SKILL.md so it does not consume model context when the skill loads.
| Skill | Adapted from |
|---|---|
k-writing-great-skills | k-writing-great-skills |
k-codebase-design | k-codebase-design |
k-diagnosing-bugs | k-diagnosing-bugs |
k-prototype | k-prototype |
The comprehensive audit includes all 58 entrypoints and their owned references, including plain SKILL.md files. Changes preserve mandatory loads and distinct contracts while removing repeated explanations and recursive loads within one invocation. Explicit corrections align spec/build regression guards, review miss-sweep auditing, capture/publication timing, scoped runtime lifecycle exceptions, and read-only tool requests. These corrections are intentional semantic differences; bounded decision checks and clause correspondence do not prove universal model equivalence.