agentskills.io specification — applied reference¶

The agentskills.io specification is the external standard every skill in this catalogue follows. This page is the applied reference: what the spec requires, how this catalogue adds to it, and how the enforcement tools verify it. The authoritative specification lives at agentskills.io; this page covers the catalogue-local application.

For how to author a skill from scratch, see How to author a skill.

Frontmatter keys¶

Six top-level keys are allowed; all others are rejected by the linter.

Everything project-specific that doesn't belong at the top level goes under metadata:.

The metadata: escape hatch¶

The metadata: key is the catalogue's extension point within the spec. Project-specific fields that don't belong at the top level live here:

metadata:
  type: skill           # skill | hook | command
  boundaries:
    - filesystem_write
    - network_fetch

The linter enforces that metadata: is a YAML mapping (not a scalar or list). Its sub-keys are not validated by the spec — they are the catalogue's own domain and must be self-consistent across the pack.

Description rules¶

The description: field drives activation — it is the single field the agent reads when deciding whether to invoke the skill. Getting it wrong means the skill either fires on the wrong prompts or fails to fire on the right ones.

Four rules the linter enforces:

1. Single-line scalar. No YAML folded (>) or literal (|) blocks. No continuation lines (an indented next line). These parse as valid YAML but break on some adapter targets.
2. No structural YAML characters unquoted. A bare : mid-description, a leading #, &, *, or [, or whitespace-then-# change the parse. Wrap the whole value in double quotes if you need any of these characters.
3. Trigger-phrased. Start with "Use when…" or name the trigger condition explicitly. Describe when to activate, not what the implementation does.
4. Under 1024 characters. Some adapter targets truncate beyond this.

Run python3 tools/lint-skill-spec.py — it checks all four rules and is the authoritative source. Do not memorise the rules from this page; run the linter.

Directory layout¶

A skill is a directory with SKILL.md and four optional subdirectories. The linter only blesses these four:

How references/ works — context on demand¶

Context that a skill needs but does not use on every invocation belongs in references/, not in the skill body. The skill body loads a reference file at the moment the workflow reaches the branch that needs it — "load references/strategy-X.md now" — and routes to exactly one branch per run.

This has two effects: the skill body stays lean at the point of activation, and the agent carries only the context relevant to the current invocation rather than all possible branches. A skill body that exceeds 500 lines is a signal that detail is embedded that should be in references/. A skill that pre-loads all its reference files unconditionally, or embeds large knowledge blocks inline in the body, violates this pattern.

Path discipline¶

All paths within a skill (scripts, references, assets) are relative to the skill's own directory. A skill must not reference:

• Absolute filesystem paths
• Paths outside the pack's source tree (packs/<pack>/.apm/skills/<name>/)
• Paths that are only valid in a particular repo checkout or deployment
• Hardcoded org-specific locations or knowledge stores

Context the skill needs from the workspace (the CHARTER, the active adapter, the pack inventory) is read by the skill's own procedures at runtime from the workspace's standard structure — not embedded as a hardcoded path. This is what makes a skill portable: any team can install it and have it behave consistently, without configuring input locations.

Independent installation¶

Skills are self-contained by design. A skill that requires a tool, package, or sibling skill declares its dependencies explicitly, detects their presence at the start of its workflow, and fails with a clear remediation message if they are absent. No installation happens silently.

Three tiers govern how dependencies are handled:

Tier 1 — Declare, detect, fail clean (the default for all dependencies). Name the dependency in ## Prerequisites. Detect it with shutil.which() for binaries or a library import probe for packages. On absence: stop and emit the exact install command from Prerequisites — nothing more. This is the correct tier for almost all skill dependencies. The user's environment is not the skill's to modify without explicit consent.

Tier 2 — Opt-in, gated, idempotent (allowed, not the default). A skill may install a dependency only when: the install is a single deterministic command, it needs no root, and it uses a package manager the user demonstrably already has. The pattern is always: detect → ask for consent → install → re-verify. Silent install and assumed PATH after install are both disallowed even in Tier 2.

Tier 3 — Banned. Silent auto-install. Assumed root or sudo. Pipe-to-shell installers without explicit consent. Trusting PATH without re-verifying after install. None of these are acceptable regardless of convenience.

The three tiers are what make independent installation safe: any team member can install any profile and have every skill work — or fail clean with a precise remediation — without coordinating a shared environment or configuring shared file locations.

OWASP Agentic Skills Top 10 v1.0 — mapping to the agentskills.io surface¶

The OWASP Agentic Skills Top 10 v1.0 (AST01–AST10) is a public security standard for skill-file authoring, distribution, and installation. The checks map directly onto the agentskills.io surface:

AST02 (supply chain) is handled by the supply-chain security module. AST08 is addressed structurally by the tool/hybrid/reason review taxonomy built into the adversarial review process.

Every skill converged into this catalogue is reviewed against AST01–AST10 before landing. Every skill authored here is reviewed against the same checks in the adversarial review step of the work-loop.

Enforcement tools¶

The linters are the mechanical authority. Where this page conflicts with the linters or the specification at agentskills.io, the linters and the upstream spec are correct.