Author Skills

Author Skills

Skill for creating and distributing Agent Skills through a Great Docs documentation site. An Agent Skill is a structured Markdown file (SKILL.md) that gives AI coding agents context about a package, its API, and best practices.

Great Docs supports three scenarios for skills, each with a different level of effort and control.

The three scenarios

Scenario 1: Automatic generation

Great Docs generates a skill.md automatically from your package metadata, API reference sections, and great-docs.yml config. This is the zero-effort default.

How it works: during great-docs build, the tool reads your pyproject.toml (for name, description, license, Python version), your API reference sections, and any skill.* config keys. It produces a skill file with installation instructions, an API overview, gotchas, best practices, and resource links.

Config options that enrich the auto-generated skill:

# great-docs.yml
skill:
  enabled: true # default; set false to skip
  well_known: true # publish to .well-known/agent-skills/
  gotchas:
    - "Column expressions are lazy; call .collect() to materialize."
    - "Method chaining returns a new object; the original is not mutated."
  best_practices:
    - "Prefer method chaining over intermediate variables."
  decision_table:
    - need: "Create a table from a dict"
      use: "GT(data)"
    - need: "Format currency values"
      use: "fmt_currency()"
  extra_body: "skills/extra-skill-content.md"

When to use this scenario: you want a skill page with minimal effort and are satisfied with auto-generated content derived from your API reference.

Scenario 2: Single hand-written skill

Write a SKILL.md by hand (or with LLM assistance) and point great-docs.yml at it. Great Docs copies it into the build and generates the Skills page from it.

Directory layout:

project-root/
├── skills/
│   └── my-package/
│       ├── SKILL.md
│       └── references/
│           ├── api-patterns.md
│           └── gotchas.md
└── great-docs.yml

Config:

# great-docs.yml
skill:
  file: skills/my-package/SKILL.md

Great Docs copies the file to <docs>/skill.md, places it under .well-known/agent-skills/<name>/SKILL.md, and generates the Skills page with install instructions and the full skill content.

When to use this scenario: you want full editorial control over the skill content, including custom sections, curated examples, and reference files that go beyond what automatic generation can produce.

Scenario 3: Multiple named skills

Distribute several focused skills from a single site. Each skill gets its own panel on the Skills page (with a switcher bar) and its own entry in .well-known/agent-skills/index.json for npx skills add discovery.

Directory layout:

project-root/
├── skills/
│   ├── my-package/
│   │   ├── SKILL.md
│   │   └── references/
│   ├── write-guides/
│   │   ├── SKILL.md
│   │   └── references/
│   └── review-code/
│       ├── SKILL.md
│       └── references/
└── great-docs.yml

Config:

# great-docs.yml
skill:
  skills:
    - name: my-package
      file: skills/my-package/SKILL.md
    - name: write-guides
      file: skills/write-guides/SKILL.md
    - name: review-code
      file: skills/review-code/SKILL.md

The first entry becomes the primary skill.md at the site root. All entries appear in the switcher bar and are individually installable via npx skills add.

When to use this scenario: your project has distinct focus-area skills (e.g., one for general usage, one for contributing, one for configuration) and you want users to install exactly what they need.

Quick start

Create a hand-written skill in three steps:

mkdir -p skills/my-package/references

cat > skills/my-package/SKILL.md << 'SKILL_EOF'
---
name: my-package
description: >
  Use the my-package Python library. Covers installation, core API,
  and common patterns.
license: MIT
compatibility: Requires Python >=3.11.
metadata:
  author: your-name
  version: "1.0"
  tags:
    - python
    - my-package
---

# my-package

Short description of what the package does and when to use it.

## Installation

```bash
pip install my-package

When to use what

API overview

Core

• Widget(): Create a new widget.
• Widget.style(): Apply styling to a widget.

Gotchas

1. Immutable by default. Methods return new objects.
2. Lazy evaluation. Call .render() to produce output.

Best practices

• Prefer method chaining over intermediate variables.
• Use type hints in all public API calls. SKILL_EOF

Then add one line to `great-docs.yml`:

```yaml
skill:
  file: skills/my-package/SKILL.md

Run great-docs build and verify the Skills page.

Skill directory structure

skills/author-skills/
├── SKILL.md
└── references/
    ├── skill-anatomy.md
    └── config-reference.md

Writing a SKILL.md

Frontmatter

Every SKILL.md starts with YAML frontmatter:

---
name: my-package
description: >
  One-paragraph description of the skill (max 1024 characters).
license: MIT
compatibility: Requires Python >=3.11.
metadata:
  author: your-github-handle
  version: "1.0"
  tags:
    - python
    - relevant-topic
---

The required and optional keys are documented in the references/skill-anatomy.md companion file.

Body structure

A well-structured skill follows this outline:

# Package Name
Opening paragraph (what, when, why).

## Installation
pip install command.

## When to use what
Decision table mapping needs to API calls.

## API overview
Sections matching your API reference, with one-line summaries.

## Gotchas
Numbered list of common pitfalls.

## Best practices
Bullet list of recommended patterns.

## Resources
Links to docs, llms.txt, and source code.

Reference files

Place companion Markdown files in a references/ subdirectory alongside the SKILL.md. These files are copied into .well-known/agent-skills/<name>/references/ and are available to agents that install the skill.

Use reference files for content that is too detailed for the main SKILL.md: style guides, checklists, pattern libraries, and decision matrices.

Writing tips

Follow these guidelines when writing skill content:

• Write for an LLM reader, not a human. Be explicit about distinctions that a model might confuse (e.g., {python} vs {.python}).
• Use concrete examples over abstract descriptions.
• Keep the decision table ("When to use what") actionable: each row should map a task to a specific function or method.
• Avoid emoji, em dashes, and starting a list without introductory text.
• Keep the SKILL.md under 2000 lines. Move detailed reference material into companion files.