Add skill-manager skill (migrated from skill-creator) with deploy action
- Skill content moved from ~/.agents/skills/skill-creator, renamed to skill-manager - New deploy CLI action: installs any skill via absolute-path symlinks (or copies) into $HOME/.agents/skills, $HOME/.claude/skills and $HOME/.cline/skills - Taskfile + shell module wrappers (task deploy / cli:deploy) - SKILL.md: deploy docs, origin-repository/origin-path metadata Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Claude Fable 5
@@ -0,0 +1,213 @@
|
||||
# Agent Skills — Full Specification Reference
|
||||
|
||||
Source: https://agentskills.io/specification
|
||||
|
||||
## Directory structure
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Required: metadata + instructions
|
||||
├── scripts/ # Optional: executable code
|
||||
├── references/ # Optional: documentation loaded on demand
|
||||
├── assets/ # Optional: templates, resources
|
||||
└── ... # Any additional files or directories
|
||||
```
|
||||
|
||||
## SKILL.md format
|
||||
|
||||
The file must contain YAML frontmatter followed by Markdown content.
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter fields
|
||||
|
||||
| Field | Required | Constraints |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Max 64 chars. Lowercase letters, numbers, hyphens only. No leading/trailing/consecutive hyphens. Must match the parent directory name. |
|
||||
| `description` | Yes | Max 1024 chars. Non-empty. Describes what the skill does and when to use it. |
|
||||
| `license` | No | License name or reference to a bundled license file. |
|
||||
| `compatibility` | No | Max 500 chars. Indicates environment requirements (product, packages, network, etc.). |
|
||||
| `metadata` | No | Arbitrary key-value mapping (string → string) for additional metadata. |
|
||||
| `allowed-tools` | No | Space-separated string of pre-approved tools. (Experimental) |
|
||||
|
||||
---
|
||||
|
||||
## `name` field
|
||||
|
||||
Rules:
|
||||
- 1–64 characters
|
||||
- Only: lowercase letters `a-z`, digits `0-9`, hyphens `-`
|
||||
- Must not start or end with a hyphen
|
||||
- Must not contain consecutive hyphens `--`
|
||||
- **Must match the parent directory name exactly**
|
||||
|
||||
Valid examples:
|
||||
```yaml
|
||||
name: pdf-processing
|
||||
name: data-analysis
|
||||
name: code-review
|
||||
```
|
||||
|
||||
Invalid examples:
|
||||
```yaml
|
||||
name: PDF-Processing # uppercase not allowed
|
||||
name: -pdf # cannot start with hyphen
|
||||
name: pdf--processing # consecutive hyphens not allowed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `description` field
|
||||
|
||||
Rules:
|
||||
- 1–1024 characters
|
||||
- Should describe both **what** the skill does and **when** to use it
|
||||
- Include specific keywords that help agents identify relevant tasks
|
||||
|
||||
**Good example:**
|
||||
```yaml
|
||||
description: >
|
||||
Extracts text and tables from PDF files, fills PDF forms, and merges
|
||||
multiple PDFs. Use when working with PDF documents or when the user
|
||||
mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Poor example:**
|
||||
```yaml
|
||||
description: Helps with PDFs.
|
||||
```
|
||||
|
||||
Principles for effective descriptions:
|
||||
- Use imperative phrasing: "Use this skill when…" not "This skill does…"
|
||||
- Focus on user intent, not internal mechanics
|
||||
- Be explicit about indirect triggers: "even if they don't explicitly mention 'CSV'"
|
||||
- Err on the side of being specific and slightly pushy
|
||||
- Keep it concise — a few sentences to a short paragraph
|
||||
|
||||
---
|
||||
|
||||
## `license` field
|
||||
|
||||
- Specifies the license applied to the skill
|
||||
- Keep it short — either the name of a license or the name of a bundled license file
|
||||
|
||||
Example:
|
||||
```yaml
|
||||
license: Apache-2.0
|
||||
license: Proprietary. LICENSE.txt has complete terms.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `compatibility` field
|
||||
|
||||
- 1–500 characters if provided
|
||||
- Only include if your skill has specific environment requirements
|
||||
- Can indicate: intended product, required system packages, network access
|
||||
|
||||
Examples:
|
||||
```yaml
|
||||
compatibility: Designed for Claude Code (or similar products)
|
||||
compatibility: Requires git, docker, jq, and access to the internet
|
||||
compatibility: Requires Python 3.14+ and uv
|
||||
```
|
||||
|
||||
Most skills do not need this field.
|
||||
|
||||
---
|
||||
|
||||
## `metadata` field
|
||||
|
||||
- A map from string keys to string values
|
||||
- Use for storing additional properties not defined by the spec
|
||||
- Make key names reasonably unique to avoid conflicts
|
||||
|
||||
Example:
|
||||
```yaml
|
||||
metadata:
|
||||
author: example-org
|
||||
version: "1.0"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `allowed-tools` field
|
||||
|
||||
- A space-separated string of tools pre-approved to run
|
||||
- Experimental — support varies between agent implementations
|
||||
|
||||
Example:
|
||||
```yaml
|
||||
allowed-tools: Bash(git:*) Bash(jq:*) Read
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Body content
|
||||
|
||||
The Markdown body after the frontmatter contains the skill instructions.
|
||||
|
||||
Recommended sections:
|
||||
- Step-by-step instructions
|
||||
- Examples of inputs and outputs
|
||||
- Common edge cases
|
||||
|
||||
The agent loads the entire body when the skill activates. Keep it under 500 lines. Move longer reference material to separate files.
|
||||
|
||||
---
|
||||
|
||||
## Progressive disclosure
|
||||
|
||||
Skills are loaded in three stages:
|
||||
|
||||
| Stage | Content | Size |
|
||||
|-------|---------|------|
|
||||
| Startup | `name` + `description` only | ~100 tokens |
|
||||
| Activation | Full `SKILL.md` body | < 5,000 tokens recommended |
|
||||
| On demand | Files in `scripts/`, `references/`, `assets/` | As needed |
|
||||
|
||||
Keep `SKILL.md` under 500 lines. Move detailed reference material to separate files and tell the agent *when* to load them — not just "see references/ for details."
|
||||
|
||||
---
|
||||
|
||||
## File references
|
||||
|
||||
Use relative paths from the skill root:
|
||||
|
||||
```markdown
|
||||
See [the reference guide](references/REFERENCE.md) for details.
|
||||
|
||||
Run the extraction script:
|
||||
scripts/extract.py
|
||||
```
|
||||
|
||||
Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
|
||||
|
||||
---
|
||||
|
||||
## Optional directories
|
||||
|
||||
### `scripts/`
|
||||
|
||||
Contains executable code agents can run. Scripts should:
|
||||
- Be self-contained or clearly document dependencies
|
||||
- Include helpful error messages
|
||||
- Handle edge cases gracefully
|
||||
|
||||
Supported languages depend on the agent implementation. Common: Python, Bash, JavaScript.
|
||||
|
||||
### `references/`
|
||||
|
||||
Contains documentation agents read on demand:
|
||||
- `REFERENCE.md` — Detailed technical reference
|
||||
- `FORMS.md` — Form templates or structured data formats
|
||||
- Domain-specific files (`finance.md`, `legal.md`, etc.)
|
||||
|
||||
Keep individual reference files focused. Agents load these on demand — smaller files = less context used.
|
||||
|
||||
### `assets/`
|
||||
|
||||
Contains static resources:
|
||||
- Templates (document, configuration)
|
||||
- Images (diagrams, examples)
|
||||
- Data files (lookup tables, schemas)
|
||||
Reference in New Issue
Block a user