# dsh-skillport — pinned spec revision

Skillport implements the **Agent Skills** `SKILL.md` format. Because the
standard is young and versioned, we pin exactly which revision we implement
and re-check it on every release.

## Pin

- **Specification:** Agent Skills `SKILL.md` (directory-per-skill + YAML
  frontmatter + progressive disclosure), as published by Anthropic and
  mirrored by the community reference at
  `agentskills/agentskills` → `docs/specification.mdx`.
- **Pinned revision:** `5d4c1fda` (2026-08-14 fetch) of
  <https://github.com/agentskills/agentskills/blob/main/docs/specification.mdx>
  — the canonical source we validated the frontmatter grammar and validation
  rules against (mirrors Anthropic's agent-skills documentation).
- **DSH platform pin:** `@deepseek-ai/dsh-base@0.1.0-rc.6` (the skill registry
  `ctx.skills`, the native filesystem provider, and the tool-skill catalog +
  loader we integrate with).

## What we implement (Tier 1 — the actual product)

1. **`SKILL.md` loader:** directory-per-skill with a `SKILL.md` containing
   YAML frontmatter + Markdown body; also flat `.md` skills (DSH-native
   extension). Body loaded on trigger via the platform's native `skill` tool.
2. **Frontmatter fields** (pinned spec):

   | Field | Required | Constraints |
   |---|---|---|
   | `name` | yes | 1–64 chars; `a-z0-9-` only; no leading/trailing/consecutive hyphens; should match the parent directory name |
   | `description` | yes | 1–1024 chars; what it does + when to use it |
   | `license` | no | license name or reference to a bundled file |
   | `compatibility` | no | 1–500 chars; environment requirements |
   | `metadata` | no | string→string map (clients may add their own keys) |
   | `allowed-tools` | no | space-separated pre-approved tools (experimental; accepted, surfaced as metadata) |

   DSH-native extra fields accepted for compatibility: `whenToUse`,
   `disable-model-invocation`, `user-invocable`.
3. **Discovery roots** (project + user, precedence DSH-native > Claude >
   Codex > Gemini; extras lowest):

   | Source | Path | Rank |
   |---|---|---|
   | DSH-native | `.dsh/skills/`, `~/.dsh/skills/` | 100 / 400 |
   | Claude Code | `.claude/skills/`, `~/.claude/skills/` | 150 / 450 |
   | Codex / open | `.agents/skills/`, `~/.agents/skills/` | 200 / 500 |
   | Gemini | `~/.gemini/antigravity/skills/` | 550 |
   | Configurable extras | `extraPaths` (config) | 650 |

   `.dsh` and `.agents` are scanned natively by `@deepseek-ai/dsh-skill-filesystem`
   when it is mounted; skillport detects that and does **not** double-scan
   (check-first, no double-injection). If the native provider is absent,
   skillport scans those sets itself so the full table holds in any
   composition.
4. **Progressive disclosure:** names + descriptions enter the session catalog
   through the native tool-skill injection; full bodies load on demand through
   the native `skill` tool, which resolves bundled resources against the
   skill's directory (`resourceBase`).

## Tier 2 — adjacent formats (best-effort, clearly labeled)

- **Cursor rules** `.cursor/rules/*.mdc` → converted to model-invocable
  skills (frontmatter `description`, `globs`, `alwaysApply` → trigger +
  body). Source `cursor`.
- **Claude Code slash commands** `.claude/commands/*.md` → converted to
  **user-invokable** skills (invoked as `/name`). Source `claude-command`.
- **Context files** `AGENTS.md` / `CLAUDE.md` → injected as project context
  **only if** DSH does not already do so natively (`dsh-agent-instructions`
  handles both; skillport checks first and skips to avoid double-injection).

## Non-goals (README spells these out)

Claude Code plugins/hooks/subagents, MCP config translation, Codex/Cursor
extension binaries — anything with executable host-specific semantics.