tap-skill-authoring · diff
git:20260918.2a266c7 to git:20261013.a69e0bb
111 added, 194 removed. Audit A to A.
---
name: tap-skill-authoring
title: "Tap Skill Authoring"
- description: "Complete guide for creating AgentSkills-compliant SKILL.md packs in the octomind-tap registry: frontmatter fields, body structure, auto-activation rules, validate scripts, and quality principles. Activate when creating or editing skills/<name>/SKILL.md files."
+ description: "Guide for creating AgentSkills-compliant SKILL.md packs in an Octomind tap: frontmatter fields, auto-activation rules and domains, bundled resources, validate scripts, body structure, tone, and the lint gates. Activate when creating or editing skills/<name>/SKILL.md files."
license: Apache-2.0
- compatibility: "Requires: any Octomind tap with a skills/ directory."
+ compatibility: "Requires: an Octomind tap checkout with scripts/lint-skills.sh."
domains: octomind
---
## Overview
- A skill is a reusable instruction pack stored under `skills/<name>/SKILL.md`. When activated in an Octomind session via `skill(action="use", name="<name>")`, the skill's full content is injected into the AI's context — giving it domain-specific knowledge, conventions, and workflows on demand.
+ A skill is a reusable instruction pack at `skills/<name>/SKILL.md`. When it activates — preloaded, auto-activated by its rules, or loaded with `skill(action="use")` or `/skill <name>` — its body is injected into the session's context. Skills don't define a role, model, or tools; they add focused knowledge any agent in their domain can use.
- Skills are not agents — they don't define a role or model. They are context injections: focused, composable knowledge packs that any agent can load on demand.
+ ## Mental model
- ## Instructions
+ A skill is a checklist for a model that already knows the field. Anthropic's skill guidance starts from "Claude is already very smart — only add context Claude doesn't already have." Every token ships on every activation, so the body carries decisions, conventions, and gates, not textbook background. Activation is decided by the frontmatter (`domains` plus `rules`), so the frontmatter is as much a part of the design as the body.
- ### Directory Structure
+ ## Rules
+ ### Directory structure
+
```
skills/<skill-name>/
- ├── SKILL.md # Required: metadata + instructions
- ├── scripts/ # Optional: executable code the skill references
- ├── references/ # Optional: supplementary docs (REFERENCE.md, FORMS.md, etc.)
- ├── assets/ # Optional: templates, config files, resources
- └── validate # Optional: output validation script (must be chmod +x)
+ ├── SKILL.md # required
+ ├── reference/ # long reference files, cited from the body and lint-checked
+ ├── scripts/ # executables the skill tells the agent to run
+ ├── assets/ # templates and resources
+ └── validate # optional output validator (chmod +x)
```
- ### SKILL.md Format
+ On activation the runtime lists every file under `scripts/`, `references/`, and `assets/` with absolute paths in a Skill Resources section. `reference/` (singular, the tap convention) is not in that list, so cite those files from the body by path; `lint-skills.sh` fails if a cited `reference/<file>` does not exist. Keep references one level deep from SKILL.md.
+ ### Frontmatter
+
```markdown
---
name: skill-name
- title: "Skill Title (5–60 chars)"
+ title: "Skill Title"
description: "What this skill does and when to use it."
license: Apache-2.0
- compatibility: "Environment requirements: tools needed, OS, network access."
- capabilities: versioning memory-read
- domains: developer devops
+ compatibility: "Requires: tool1. macOS/Linux."
+ capabilities: versioning
+ domains: developer
rules:
- - file(marker-file) # OR: file exists in workdir (glob ok: *.rs)
- - content(keyword) # OR: user message contains whole word
- - file(marker) content(keyword) # OR: BOTH conditions (AND within one line)
- - grep(pattern, glob) # OR: file content matches
- - match(regexp) # OR: user message matches regexp
- - env(VAR) # OR: env var is set
- - env(VAR=value) # OR: env var equals value
- # metadata:
- # author: name
- # version: "1.0"
- # allowed-tools: shell view text_editor
+ - file(Cargo.toml)
+ - content(rust) content(async)
---
-
- # Skill Title
-
- ## Overview
- ...
-
- ## Instructions
- ...
-
- ## Examples
- ...
```
- ### Frontmatter Fields
-
| Field | Required | Rules |
|-------|----------|-------|
- | `name` | ✅ | Max 64 chars. Lowercase, numbers, hyphens only. No leading/trailing hyphen. Must match directory name exactly. |
- | `title` | ✅ | 5–60 chars. Short human-readable label. |
- | `description` | ✅ | Max 1024 chars. Describes what the skill does and when to use it. |
- | `capabilities` | optional | Capabilities to auto-load when skill activates. Space-delimited or array. |
- | `domains` | optional | Agent categories for auto-activation scoping. Without this, skill is manual-only. |
- | `rules` | optional | Auto-activation rules. If any matches, skill activates. Omit for manual-only. |
- | `license` | optional | License name (e.g. `Apache-2.0`, `MIT`). |
- | `compatibility` | optional | Max 500 chars. Environment requirements. |
- | `metadata` | optional | Arbitrary key-value mapping (author, version, tags, etc.). |
- | `allowed-tools` | optional | Space-delimited pre-approved tools (experimental). |
-
- ### Body Structure (mandatory section order — 2026 standard)
-
- Skills are loaded into agent context as Markdown. They follow a fixed section order grounded in the U-shape attention curve: the start (Overview) and the end (Checklist + References) get the most attention, the middle holds the bulk knowledge with clear headers as retrieval anchors.
-
- ```
- 1. Overview ← primacy: why this skill, when to activate (2–4 sentences)
- 2. Mental model ← core principles or governing concepts (the framing)
- 3. Rules / Instructions ← the actual rule content — tables, bullets, decision guides
- 4. Examples ← concrete bad → good or input → output pairs
- 5. Diagnostic / Checklist ← recency: verifiable checks before shipping
- 6. Composition / References ← how this skill pairs with siblings (within-domain only) + external sources
- ```
-
- Why this order:
- - Overview first — reader (human or AI) needs to know if this skill applies before reading rules
- - Mental model before rules — gives the framing so individual rules make sense
- - Rules in the middle, but headed with clear `## H2` anchors so they survive "lost in the middle"
- - Examples after rules so the rules are concrete by the time they're seen
- - Checklist near the end — recency: it's the last actionable thing the model sees, so it acts as a final gate
- - References last — outbound links, lowest attention need
-
- Section authoring rules:
- - Overview — 2–4 sentences. Names the problem, the trigger, and the outcome. No fluff.
- - Mental model — Optional but recommended for any skill with >3 rules. Without it, rules read as a list; with it, they read as a system.
- - Rules — Tables for decisions, bullet lists for sequential rules, prose only when the why is non-obvious. Never write paragraph-after-paragraph.
- - Examples — Bad → Good is the strongest format. Show the AI tell, then the fix. One concrete example beats three abstract rules.
- - Checklist — Verifiable items only. "Score 0–10 on each dimension" beats "Make sure quality is high."
- - References — Within-domain skills, external authoritative sources, spec links. Don't list every blog post you read.
-
- Token discipline (Claude 4.7 / 2026):
- - Target: under 3000 words. Anthropic recommends "under 500 lines" for optimal performance.
- - Hard cap: 4500 words. Above this, `lint-skills.sh` fails with `BODY_TOO_LONG` and the skill must be split via progressive disclosure (SKILL.md as navigator + `reference/*.md` files loaded on demand).
- - Beyond ~3000 words, recall on individual rules starts degrading (context rot)
- - Cut decorative prose; if a sentence doesn't make a rule clearer, delete it
- - Be explicit — Claude 4.7 doesn't bridge implicit gaps anymore
-
- Markdown discipline (token waste — hard-blocked by `lint-skills.sh`):
- - No `# H1` at the top of the body. Frontmatter `title:` is the canonical title; an H1 duplicates it. Body starts with `## Overview` directly.
- - No `**bold**` outside code. Use `## H2` and `### H3` headers for structure; the model doesn't need bold for emphasis.
- - No `*italic*` and no `***bold-italic***`. Pure decoration, zero semantic value.
- - No `---` horizontal-rule separators inside the body. `## H2` headers already mark sections; HR is visual noise.
- - Tables and code fences stay — they are structural, not decorative.
-
- The rule of thumb: every character ships to the model on every activation. If removing it doesn't change what the model would do, remove it.
-
- Tone calibration (Claude 4.6+ over-emphasis — mandatory awareness):
+ | `name` | yes | ≤64 chars, lowercase letters, digits, hyphens; no leading/trailing hyphen; equals the directory name |
+ | `title` | yes (tap lint) | 5–60 chars |
+ | `description` | yes | 20–1024 chars, third person, what it does plus when to use it with concrete trigger terms |
+ | `domains` | for auto-activation | Space-separated or array; each value must be an existing `agents/<domain>/` directory (lint); the runtime also accepts `*` for every domain, but tap lint rejects it |
+ | `rules` | for auto-activation | List of rule expressions, below |
+ | `capabilities` | optional | Capabilities enabled when the skill activates; each must exist under `capabilities/` (lint) |
+ | `compatibility` | optional | ≤500 chars, environment only (tools, OS, network) |
+ | `license`, `metadata`, `allowed-tools` | optional | `allowed-tools` is space-separated; missing tools are reported as an incompatibility |
- Skills load into the agent context as instruction packs, so the same calibration rules that apply to agent prompts apply here. Claude 4.5+ over-triggers on aggressive language that older models needed.
+ The runtime parser reads `name`, `description`, `compatibility`, `license`, `allowed-tools`, `capabilities`, `domains`, and `rules`; a skill without `name` or `description` is skipped. Without both `domains` and `rules`, a skill is manual-only.
- - `CRITICAL: YOU MUST X` → `X.`
- - `🚨 HARD RULES` + stacked `NEVER`/`ALWAYS` bullets → plain `Don't …` / `Do …` in the Rules section
- - `MANDATORY:` headers → drop, use descriptive section names
- - `NEVER X` → `Don't X.` (capitals reserved for one or two genuine safety hard-stops)
- - `ALWAYS X` → `Do X.` or fold into a positive rule
+ ### Auto-activation rules
- The substance test: delete the `NEVER`/`ALWAYS`/`MUST` and lowercase the line. Does the rule still make sense? Soften it. Does it read as filler once softened? Cut it.
+ Rules are evaluated on fresh user messages when `[skills] auto_activation` is on and the session domain is in `domains`. Each `- ` item is an OR branch; several expressions on one line are ANDed.
- Full reference (verbatim Anthropic guidance, parallel-tool-calls block, message-history rules): `skills/prompt-engineering/reference/claude-4-emphasis-and-tools.md`.
+ | Expression | Matches when |
+ |------------|--------------|
+ | `file(<path or glob>)` | Path exists in the workdir, or the glob matches (`*.rs`, `src/**/*.go`) |
+ | `content(<word>)` | User message contains the word (whole word, case-insensitive) |
+ | `match(<regex>)` | User message matches the regex (nested parentheses are fine) |
+ | `grep(<pattern>[, <glob>])` | A gitignore-respecting workdir file contains the pattern; the glob filters by file name only (`*.toml`, not `src/**/*.rs`) |
+ | `env(<VAR>)` / `env(<VAR>=<value>)` | Variable set and non-empty / equals value |
+ | `bin(<command>)` | Command found on `PATH` |
+ | `workdir(<text>)` | Working-directory path contains the text (case-insensitive) |
+ | `session(<text>)` | Session name contains the text (case-insensitive) |
+ | `semantic(<phrase>[, <threshold>])` | Embedding cosine between the message and the phrase clears the threshold (default 0.65) |
- Bloat prevention (the three patterns that cause skills to outgrow the cap):
+ Deterministic matches activate directly. Semantic-only candidates must also beat the runner-up by a 0.06 margin, so near-ties abstain. Adding or changing `semantic(...)` phrases changes the tap embedding model's training data — see the `tap-model-training` skill.
- 1. Default to skip — for every paragraph longer than 2 sentences, ask: "what specifically does this tell the model that it doesn't already know?" If the answer is general industry context, history, or motivation that Claude already has, cut it. Skills are checklists for the model that already knows the domain, not textbooks. Anthropic's stance: "Default assumption: Claude is already very smart. Only add context Claude doesn't already have."
- 2. Examples cap — keep 2–3 best examples in SKILL.md (bad → good with one-line caption per pair). The rest go in `reference/<topic>.md` and load on demand. An Examples section over ~800 words is almost always duplicating rules.
- 3. Reference content goes in `reference/*.md`, not in SKILL.md — long tables of values, exhaustive option lists, full schema dumps, and platform-history detail belong in `reference/*.md` files that are loaded only when the model needs them. SKILL.md is the navigator: rules + decision guide + 2–3 examples + pointers.
+ ### Validate script
- When a skill exceeds the soft 3000-word warning, audit before adding more. The fix is almost always trimming teach-mode paragraphs in Instructions, not extracting structure into more references.
+ `skills/<name>/validate` runs at the end of each assistant turn while the skill is active, only when `[skills] auto_validation = true` (default `false`), and only for skills that come from a tap. Contract: argv[1] is `assistant`, the final assistant message arrives on stdin, cwd is the project workdir. A non-zero exit with non-empty stderr counts as a failure and the stderr is fed back to the model; retries per skill are capped by `[skills] max_retries`, timeout by `validation_timeout`. Make it executable.
- ### Auto-Activation Rules
+ ### Body structure
- Skills with both `rules:` and `domains:` can auto-activate without the AI calling the skill tool. Logic: OR between items, AND within a single item.
+ Fixed section order, U-shaped for attention: the opening and the closing get read most carefully, the middle relies on headers as anchors.
- ```yaml
- rules:
- - file(Cargo.toml) # OR: Rust project marker exists
- - content(rust) # OR: user message contains "rust"
- - file(Cargo.toml) content(async) # OR: BOTH file exists AND message has "async"
```
-
- | Expression | Matches when |
- |------------|-------------|
- | `file(<glob>)` | File matching glob exists in working directory |
- | `content(<word>)` | User message contains the word (whole-word, case-insensitive) |
- | `match(<pattern>)` | User message matches the regular expression |
- | `grep(<pattern>, <glob>)` | A file matching glob contains a line matching pattern |
- | `env(<VAR>)` | Environment variable is set (non-empty) |
- | `env(<VAR>=<value>)` | Environment variable equals value |
-
- Skills without `rules:` are manual-only — they never auto-activate.
-
- ### Validate Script
+ ## Overview why and when (2–4 sentences)
+ ## Mental model governing principles
+ ## Rules tables, bullets, decision guides
+ ## Examples bad → good pairs
+ ## Checklist verifiable gates before shipping
+ ## Composition / References sibling skills in the same domain, sources
+ ```
- A `validate` script at `skills/<name>/validate` checks LLM output quality at the end of each assistant turn:
- - Must be executable (`chmod +x`)
- - exit 0 → output is valid
- - exit non-zero → stderr is fed back to the LLM for correction (retries capped by `[skills] max_retries`)
+ - Overview names the problem, trigger, and outcome.
+ - Rules: tables for decisions, bullets for sequences, prose only when the why is non-obvious.
+ - Examples: two or three bad → good pairs with a one-line caption; more go to `reference/`.
+ - Checklist: verifiable items only.
- ### Quality Principles
+ ### Length and markdown
- 1. Specific beats generic — "Rust error handling" is more useful than "Rust development"
- 2. Instructions over descriptions — Tell the AI what to DO, not just describe the domain
- 3. Examples are gold — Every non-obvious rule needs a concrete example
- 4. One concern per skill — Don't bundle unrelated knowledge; compose multiple skills instead
- 5. Body must be actionable — If the AI can't follow the instructions directly, rewrite them
- 6. Compatibility matters — Be explicit about what tools/environment the skill requires
- 7. Stay in your domain — A skill belongs to one domain (its `domains:` field), and its body must not reach into others. No "hand off to `<other-domain>:<spec>`", no "companion agent: `<other-domain>:<spec>`", no language-specific build-agent references. The orchestrating agent composes domains; the skill stays focused on the work that lives inside its own. Cross-domain pollution makes skills brittle and creates implicit coupling that the agent layer can't override.
+ - Aim under ~2000 words. `lint-skills.sh` warns above 3000 body words and fails above 4500; Anthropic recommends keeping SKILL.md under 500 lines.
+ - Move long tables, exhaustive option lists, and schema dumps to `reference/*.md`; SKILL.md stays the navigator.
+ - No `# H1` at the top of the body (frontmatter `title` is the title), no bold, no italics, no `---` rules inside the body — all lint failures. Tables and code fences stay.
+ - Avoid time-sensitive phrasing ("before August"); write the current method.
- ### Domain Isolation (the hard rule)
+ ### Tone
- Skills are domain-scoped instruction packs. They are loaded by an agent in a specific domain (marketing, content, video, developer, etc.) and must focus only on what that domain owns. Concretely:
+ The same calibration as agent prompts: current Claude models follow instructions precisely and over-trigger on emphatic language.
- - `domains:` — single domain wherever possible. `domains: marketing content launch` couples the skill to three roles at once and is almost always wrong; pick the one that owns this skill's deliverable.
- - `compatibility:` — environment requirements only (tools, OS, network). Do NOT use it to declare "Pairs with X agent" — pairing is the orchestrator's job.
- - Body — never name agents from other domains (`content:`, `developer:`, `marketing:*`). If the work needs to be handed off, describe it as a downstream concern (e.g. "outreach copy is owned by another domain") without pinning a specific agent.
- - Within-domain skill references are fine when genuinely useful (a marketing skill mentioning a sibling marketing skill), but keep them minimal — the orchestrator decides composition.
+ - `CRITICAL: YOU MUST X` → `X.`
+ - Stacked `NEVER`/`ALWAYS` bullets → plain `Don't …` / `Do …`
+ - `MANDATORY:` headers → descriptive section names
- The architectural reason: a skill that names downstream agents bakes in routing decisions that belong to the agent that loaded it. When the orchestrator changes (e.g., a different marketing agent runs the same skill, or the content domain reuses it), those names become wrong. Keeping skills domain-isolated lets the agent layer compose them freely without rewriting skill bodies.
+ Reserve all-caps for one or two genuine safety hard-stops. Full guidance: `skills/prompt-engineering/reference/claude-4-emphasis-and-tools.md`.
- ### Creation Workflow
+ ### Domain isolation
- 1. Identify the domain knowledge to encode (conventions, workflows, checklists, decision trees)
- 2. Choose a clear, specific name: `git-workflow`, `code-review`, `rust-error-handling`
- 3. Copy `templates/skill.md` as starting point
- 4. Write frontmatter: `name`, `title`, `description`, optional `capabilities`, `domains`, `rules`
- 5. Write body: overview → instructions → examples → references
- 6. Optionally add `validate` script (`chmod +x`)
- 7. Validate: `bash scripts/lint-skills.sh skills/<name>`
- 8. Test: `skill(action="use", name="<name>")`
+ - `domains:` single-valued wherever possible — pick the domain that owns the deliverable.
+ - `compatibility:` describes the environment, never pairings with agents.
+ - The body never names agents from other domains; describe downstream work as owned by another domain. Sibling skills in the same domain may be named sparingly.
- ### Review Checklist
+ ### Creation workflow
- - [ ] Does the description tell you exactly when to activate it?
- - [ ] Body follows the canonical section order? (Overview → Mental model → Rules → Examples → Checklist → Composition / References)
- - [ ] Checklist section near the end? (recency — it's the final gate before the model acts)
- - [ ] Are the instructions specific enough to follow without guessing?
- - [ ] Are there examples for the non-obvious parts?
- - [ ] Total skill body under ~2000 words? (context rot threshold for skills)
- - [ ] Is the `name` field an exact match for the directory name?
- - [ ] Is the `compatibility` field accurate?
- - [ ] Tone calibrated for Claude 4.6+: no `CRITICAL: YOU MUST` / `🚨 HARD RULES` / stacked all-caps `NEVER`/`ALWAYS`? `Use X when ...` rather than `Default to X`?
- - [ ] Does `bash scripts/lint-skills.sh skills/<name>` pass clean?
+ 1. Identify the knowledge the model lacks: conventions, decision rules, gates.
+ 2. Pick a specific name (`rust-error-handling`, not `rust`).
+ 3. Copy `templates/skill.md`; write frontmatter, then the body in canonical order.
+ 4. Add `domains` + `rules` only if it should auto-activate; test that the rules match the intended prompts and nothing broader.
+ 5. Optionally add `validate`.
+ 6. Run `bash scripts/lint-skills.sh skills/<name>`; test with `/skill <name>` in a session.
## Examples
- ### Example 1: Minimal valid skill
+ ### Example 1: minimal valid skill
```markdown
---
name: git-workflow
title: "Git Workflow"
- description: "Git commit conventions and branch naming. Activate when committing or branching."
+ description: "Commit message conventions and branch naming. Use when committing or creating branches."
license: Apache-2.0
---
- # Git Workflow
-
## Overview
- Encodes Conventional Commits and branch naming rules.
-
- ## Instructions
- - Use `feat:`, `fix:`, `chore:` prefixes on commits
- - Branch names: `feat/short-description`, `fix/short-description`
+ Encodes Conventional Commits and branch naming.
- ## Examples
- ...
+ ## Rules
+ - Prefix commits with `feat:`, `fix:`, `chore:`.
+ - Branch names: `feat/short-description`, `fix/short-description`.
```
- ### Example 2: Skill with auto-activation
+ ### Example 2: auto-activation
```markdown
---
name: programming-rust
title: "Rust Programming"
description: "Rust idioms, error handling, async patterns. Auto-activates in Rust projects."
domains: developer
rules:
- file(Cargo.toml)
- - file(*.rs)
- - content(rust)
+ - grep(tokio, Cargo.toml) content(async)
+ - semantic(write idiomatic rust code)
---
```
- ### Example 3: Common mistake — skill trying to be an agent
+ ### Example 3: common mistakes
- ```markdown
- # ❌ WRONG — skills don't define roles, models, or capabilities wiring
- [[roles]]
- system = "..."
- temperature = 0.1
+ ❌ `# Git Workflow` as the first body line — lint fails with `BODY_HAS_REDUNDANT_H1`.
- # ✅ CORRECT — skills are pure instruction content, no TOML config
- ```
+ ❌ `grep(async_trait, src/**/*.rs)` — the glob is matched against file names only, so it never matches. Use `grep(async_trait, *.rs)`.
- ## References
+ ❌ `domains: dev` — no `agents/dev/` directory, so lint fails and it would never activate.
- - `templates/skill.md` — canonical skill template (copy to start)
- - `bash scripts/lint-skills.sh` — validates skill files
+ ## Checklist
+
+ - [ ] Description in third person, says what and when, with concrete trigger terms?
+ - [ ] `name` equals the directory; `domains` and `capabilities` reference real directories?
+ - [ ] Rules match the intended prompts and nothing broader; semantic phrases one idea each?
+ - [ ] Body in canonical order, no H1, bold, italics, or `---`; under ~2000 words?
+ - [ ] Instructions actionable and specific; examples for non-obvious rules?
+ - [ ] Tone calibrated: plain directives, all-caps only for real hard-stops?
+ - [ ] Cited `reference/` files exist; `validate` executable if present?
+ - [ ] `bash scripts/lint-skills.sh skills/<name>` passes?
+
+ ## Composition / References
+
+ - `templates/skill.md` — canonical skill template
+ - `tap-model-training` — retrain after changing `semantic(...)` phrases
- [AgentSkills specification](https://agentskills.io/specification)
+ - [Anthropic skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)