AGENTS.md · K-Dense-AI/scientific-agent-skills

Sections

1. What belongs here
2. Layout
3. Creating a skill
4. Updating a skill
5. Frontmatter
6. Body and layout
7. Validate and scan
8. Skill diagrams
9. Before opening a PR

First lines (shown under the repo's MIT license)

# Repository Guidance

This repository is a collection of Agent Skills for science and research. Every skill lives in its
own directory under `skills/` and must conform to the open
[Agent Skills specification](https://agentskills.io/specification).

Read this file before creating or changing a skill. `CONTRIBUTING.md` covers the same ground at
more length, plus the pull-request process.

## What belongs here

**In scope:** a narrow skill for one scientific package, database, platform, or research workflow —
`scanpy`, `depmap`, `benchling-integration`, `experimental-design`.

**Out of scope**, and routinely declined:

- General software-engineering or coding-judgment skills — they compete for selection on every task.
- General infrastructure with a scientific example bolted on (a vector database, a cloud SDK) —
  accepting one implies carrying every competitor.
- Broad "orchestrator" skills that route to other skills — they overlap every specialist by design.
- A second provider for a service an existing skill already reaches.

The general-purpose skills that do exist are narrow output-format helpers (`generate-image`,
`markdown-mermaid-writing`). They are not precedent for broadening scope.

## Layout

The repository root is an [Agent Plugins](https://agent-plugins.org/) 1.0.0 package: `plugin.json`
plus the portable `skills/` tree. Keep `plugin.json` valid against the Agent Plugins manifest
schema, and keep its `version` identical to `pyproject.toml` `[project].version`. Do not add
non-portable top-level fields to `plugin.json` (no inline MCP, hooks, or client-only keys — use
`mcp.json` or a reverse-domain `extensions` namespace if those are ever needed).

```text
plugin.json                 # Agent Plugins manifest (repo root)
skills/<skill-name>/
├── SKILL.md        # required
├── references/     # optional: long documentation, loaded only when needed
├── scripts/        # optional: executable helpers
└── assets/         # optional: templates and static resources
```

Only `SKILL.md` is required inside each skill. Reference other files with relative paths from the
skill root, kept one level deep.

**Tests never live under `skills/`.** A skill directory ships only what an agent loads. Checks for a
skill's scripts and structure go in the repository-level suite instead:

```text
tests/<skill-name>/          # same name as the skill directory
├── test_scripts.py
└── fixtures/                # optional test data
```

**Diagrams never live under `skills/` either.** A skill may have a generated workflow diagram at
`docs/images/<skill-name>.png`, produced by `scripts/generate_skill_image.py`. Diagrams are optional
— see [Skill diagrams](#skill-diagrams).

Tests reach their skill through an explicit anchor, never a relative walk:

```python
SKILL_ROOT = Path(__file__).resolve().parents[2] / "skills" / "<skill-name>"
```

## Creating a skill

1. Create `skills/<name>/` — **the directory name is the skill name** and must equal frontmatter
   `name`.
2. Write `SKILL.md` from the template below. Start at `metadata.version: "1.0"`.
3. Add `references/`, `scripts/`, or `assets/` only when they earn their place.
4. Run the commands and code you document. Scope claims to the release you actually tested
   ("targets stable GeoPandas 1.1.4"), and mark anything untested as illustrative.
5. If the skill ships `scripts/`, put their tests in **`tests/<name>/`** — never in the skill
   directory. Fixtures go in `tests/<name>/fixtures/`.
6. Validate and scan (below).

```markdown
---
name: skill-name
description: What the skill does and when an agent should use it, including the terms that should trigger it.
license: MIT
compatibility: Requires Python 3.12+ with <package> installed. Needs network access.
metadata:
  version: "1.0"
  skill-author: Your Name
---

# Skill Title

## When to use

Use this skill when...

## Workflow

1. ...

## Examples

...
```

## Updating a skill

1. Read the current `SKILL.md` and its supporting files first.
2. Check upstream docs — APIs move, and the skill may be pinned to an older release.
3. Make the smallest useful change.
4. **Bump `metadata.version` in the same change**: minor for normal improvements (`"1.2"` →
   `"1.3"`), major only for a breaking change or substantial redesign (`"1.9"` → `"2.0"`).
5. Re-run any example, command, or script you touched, plus `tests/<name>/` if that suite exists.
   Suites check that `metadata.version` is present and quoted, not what it equals, so a version bump
   never needs a matching test edit.
## Frontmatter

`SKILL.md` starts with YAML frontmatter. **Only these six fields are allowed** — the spec defines a
closed set, and any other top-level key is a validation error:

| Field | Required | Constraints |
| --- | --- | --- |
| `name` | Yes | 1–64 chars, lowercase letters/digits/hyphens only, no leading, trailing, or consecutive hyphens, and **must equal the directory name**. |
| `description` | Yes | 1–1024 chars. Say what the skill does *and* when to use it, with the keywords that should trigger it. Write it in third person. |
| `license` | No | License name, or a reference to a bundled license file. |
| `compatibility` | No | Max 500 chars. Environment requirements only — omit it if the skill has none. |
| `allowed-tools` | No | A **space-separated string**, e.g. `Read Write Edit Bash`. Not a YAML list, not comma-separated. |
| `metadata` | No | Mapping of string keys to **string** values, except the host manifest blocks below. Required here: `metadata.version`. |

Put anything else — authorship, upstream versions, review dates, client-specific config — inside
`metadata`, never at the top level. In particular, Hermes' top-level
`required_environment_variables` cannot be used here: it fails the validator and, because
`strictyaml` rejects the whole document, takes `name` and `description` down with it. Declare
credentials in `compatibility` and `metadata.openclaw.envVars` instead.

### Write block-style YAML, not JSON flow style

The reference validator parses frontmatter with `strictyaml`, which **rejects JSON-style flow
mappings and sequences**. A flow mapping does not merely fail one check: the whole frontmatter
fails to parse, so `name` and `description` become unreadable and the skill will not register.

```yaml
# Wrong -- breaks the validator
metadata: {"version": "1.1", "skill-author": "K-Dense Inc."}

# Right
metadata:
  version: "1.1"
  skill-author: K-Dense Inc.
```

### Quote `metadata` scalars

Quote values that would otherwise be parsed as a number, boolean, or date — `version: "1.0"`,
`last-reviewed: "2026-07-23"` — so they stay strings as the spec requires.

### Host manifest blocks stay nested mappings

`metadata.openclaw` and `metadata.hermes` are the documented exception: keep them as **nested
mappings**, not JSON strings. OpenClaw's `resolveOpenClawManifestBlock()` requires
`typeof candidate === "object"`, so a JSON string silently disables its dependency gating and
credential injection. Nested mappings still pass `skills-ref validate`.