mirror of
https://github.com/shipshitdev/skills.git
synced 2026-09-19 06:04:15 +08:00
Vincent
dbd48770f8
* docs(resources): add first-hand skill-authoring reference + repo gap analysis Extract official Agent Skills authoring guidance from 13 primary vendor sources (Anthropic Claude Code/API docs, Anthropic Engineering, agentskills.io, OpenAI Codex docs) into resources/skill-authoring/. Every rule links to its source URL; gathered 2026-06-12. - anthropic.md / codex.md: per-platform rule sets across frontmatter, naming, descriptions, structure, progressive disclosure, invocation, tool permissions, references/scripts, testing, anti-patterns - frontmatter-field-spec.md: field-by-field table incl. disallowed-tools and the live paths/context:fork bugs - checklist.md: pass/fail authoring checklist + time-sensitive known issues - sources.md: annotated bibliography - repo-gap-analysis.md: audit of .agents/SYSTEM standards + validator vs the official guidance — flags paths-broken, missing disallowed-tools in the validator, allowed-tools allowlist-not-sandbox, and the unsafe Bash(git *) example, with a prioritized fix list * docs(standards): align skill standards + validator with upstream guidance Close the currency gaps found in resources/skill-authoring/repo-gap-analysis.md between this repo's standards and first-hand Anthropic + Codex docs. SKILL-STANDARDS.md: - name: add reserved-word rule (no 'anthropic'/'claude') (G6) - description: require third person (G7) - allowed-tools: document as auto-approve allowlist, NOT a sandbox; unlisted tools stay callable. Use disallowed-tools/deny rules/hooks to actually block. Note MCP fully-qualified ServerName:tool_name (G3, G8) - add disallowed-tools to the Claude extensions table (the real blocking field) - context: fork — flag empty-output-on-guidelines-only + issue #17283 (G5) - paths — flag as broken upstream (issue #49835); use nested .claude/skills/ (G1) - replace unsafe `Bash(git *)` example with scoped read-only patterns (G4) - references: state one-level-deep rule, no A->B->C chains (G9) validate-skill-sync.sh: - add disallowed-tools to allowed_fields so it stops flagging as unsupported (G2) - warn when paths: is present, pointing at the #49835 workaround (G1) Docs/validator only — no shipped skill changes to be correct today.
5.3 KiB
5.3 KiB
Frontmatter Field Specification
Field-by-field reference, merged from the agentskills.io base spec and the Claude Code extension fields. Sourced 2026-06-12. name and description are the only required fields; everything else is an optional capability extension.
| Field | Required | Purpose | Constraints |
|---|---|---|---|
name |
Yes | Display label for the skill in listings. For plugin-root SKILL.md files (no parent directory name), also determines the command name. For directory-based skills, the directory name sets the slash command regardless of this field. | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. No consecutive hyphens (--). No XML tags. No reserved words: 'anthropic', 'claude'. Must match the parent directory name (for directory-based skills). |
description |
Yes | Primary automatic-triggering signal. Claude loads only name+description at startup for all installed skills to decide which skill is relevant. The combined description+when_to_use text is truncated at 1,536 characters in the skill listing. | Must be non-empty. Max 1,024 characters. No XML tags. Write in third person. Include both capability (what it does) and trigger context (when to use it). Front-load key terms due to truncation. |
when_to_use |
No | Supplementary trigger phrases or example requests that extend the description. Appended to description in the skill listing. | Shares the 1,536-character combined cap with description. Content after the cap is silently truncated. |
disable-model-invocation |
No | When true: removes skill description from Claude's context (Claude cannot see or auto-trigger the skill) and prevents preloading into subagents. The full skill body still loads when the user manually invokes via /skill-name. | Boolean. Default: false. Use for side-effectful workflows (deploy, commit, send messages). |
user-invocable |
No | When false: hides the skill from the / command menu. Claude can still load the skill automatically when the description matches. Does NOT block Skill tool access. | Boolean. Default: true. Setting both user-invocable: false and disable-model-invocation: true leaves the skill unreachable from all paths. |
context |
No | When set to 'fork': runs the skill in an isolated subagent with no conversation history access. Skill content becomes the subagent's entire prompt. | Valid value: 'fork'. Only use for skills with explicit actionable task instructions. Skills with guidelines only (no task) return empty output from a forked subagent. Note: as of June 2026, a known GitHub issue (#17283) indicates context:fork may not be fully honored when skills are invoked via the Skill tool. |
paths |
No | Documented to limit automatic activation to files matching glob patterns. Intended for path-scoped skill activation. | Comma-separated string or YAML list of glob patterns. CAUTION: As of v2.1.84, this field has an active bug (issue #49835) — skills with paths set become completely undiscoverable. For monorepo scoping, use nested .claude/skills/ directories within packages instead. |
hooks |
No | Lifecycle hooks scoped to this skill's active period only. Hooks are cleaned up when the skill finishes. | See Claude Code Hooks documentation for configuration format. |
argument-hint |
No | Hint shown during autocomplete to indicate expected arguments. | String. Example values: '[issue-number]' or '[filename] [format]'. |
allowed-tools |
No | Grants per-use-approval bypass for listed tools while the skill is active. Does not restrict other tools — every tool remains callable. For project skills, takes effect only after the user accepts the workspace trust dialog. | Space- or comma-separated string, or YAML list. Use fully qualified ServerName:tool_name for MCP tools. Labeled as 'experimental' in the agentskills.io spec. |
disallowed-tools |
No | Removes specific tools from Claude's available pool while the skill is active. Restriction clears when the user sends their next message. | Space- or comma-separated string, or YAML list. Use for autonomous loop skills that must never call certain tools (e.g., AskUserQuestion). |
compatibility |
No | Declares specific environment requirements such as system packages, network access needs, or target agent product. | Max 500 characters. Most skills do not need this field. Include only when the skill has genuine environment prerequisites. |
Notes that bite
- The combined
description+when_to_usetext is hard-capped at 1,536 characters in the skill listing — content past the cap is silently dropped, taking trigger keywords with it. Front-load the description. - Setting both
user-invocable: falseanddisable-model-invocation: truemakes the skill unreachable from every path. Pick at most one gate. pathsandcontext: forkeach have open runtime bugs as of June 2026 — see checklist.md before relying on them.allowed-toolsis an auto-approve allowlist, not a sandbox: a tool that is not listed is still callable; it just falls through to the normal permission prompt. To actually block a tool, usedisallowed-tools(Claude) or deny rules / hooks. See anthropic.md.