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

Need	Use
Create a widget	Widget()
Style a widget	widget.style()

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.

Workflows

Adding a skill to an existing site

1. Create the skills/<name>/ directory with a SKILL.md.
2. Optionally add a references/ subdirectory with companion files.
3. Set skill.file in great-docs.yml to point at the SKILL.md.
4. Run great-docs build and check the Skills page.

Converting from automatic to hand-written

1. Run great-docs build to generate the automatic skill.md.
2. Copy the generated file from <docs>/skill.md into skills/<name>/SKILL.md.
3. Edit the content: add custom sections, rewrite descriptions, curate the decision table.
4. Set skill.file in great-docs.yml.
5. Rebuild.

Adding a second skill (switching to multi-skill mode)

1. Create a second skills/<name>/ directory with its SKILL.md.

2. Replace the skill.file key with skill.skills in great-docs.yml:

   skill:
     skills:
       - name: original-skill
         file: skills/original-skill/SKILL.md
       - name: new-skill
         file: skills/new-skill/SKILL.md
   

3. Rebuild. The Skills page now shows a switcher bar with both skills.

Testing skill installation

Verify your skill is discoverable:

# Check the published skill
great-docs check-skill

# List all skills in the .well-known manifest
great-docs list-skills

# Test npx installation (after deploying)
npx skills add <site-url>

Discovery and distribution

Great Docs publishes skills at two well-known paths for auto-discovery by npx skills add and other agent tooling:

<site>/.well-known/agent-skills/<name>/SKILL.md
<site>/.well-known/agent-skills/index.json

The index.json manifest lists all skills with their name, description, and relative path. In multi-skill mode, each skill gets its own entry.

The root-level <site>/skill.md always contains the primary skill (the first entry in skill.skills, or the only skill).

Gotchas

1. skill.skills overrides skill.file. If both are set, skill.skills takes precedence and skill.file is ignored.
2. The name field must be unique. Each skill in skill.skills needs a distinct name. Duplicates cause the later entry to overwrite the earlier one in .well-known/.
3. Reference files must be in references/. Only files under the references/ subdirectory (relative to the SKILL.md) are copied into .well-known/. Files elsewhere are ignored.
4. Use hyphens in skill names, not underscores. The name field becomes a URL path segment (.well-known/agent-skills/<name>/), and hyphens are the standard web convention for URL slugs. Match the directory name: skills/my-skill/ with name: my-skill.
5. The first skill in skill.skills is special. It becomes the primary skill.md at the site root and is the default panel shown on the Skills page.
6. Set skill.enabled: false to disable entirely. This suppresses both automatic generation and hand-written skill processing.