From 6fcf83a663dcfc26c1ce897af3622e4cc472e8ef Mon Sep 17 00:00:00 2001 From: Jonathan Bragg Date: Mon, 11 May 2026 13:43:47 -0700 Subject: [PATCH] Bring bundled skill frontmatter into Agent Skills spec compliance Every bundled SKILL.md in skills/* violated the Agent Skills spec (https://agentskills.io/specification) in two ways: - 'name': spec requires lowercase letters/numbers/hyphens matching the parent directory name. Existing skills used display strings. - 'allowed-tools': spec requires a space-separated string. Existing skills used YAML list syntax. Inspect_ai's read_skills() (called transitively by any inspect_swe agent via install_skills(), and any consumer using the skills-ref validator) rejects the existing format. Claude Code's own parser is more permissive and accepts both forms. Adds scripts/validate-skills.py and a 'make check-skills' target, wired into the CI workflow, so regressions to either field get caught at PR time. --- .github/workflows/ci.yml | 3 + Makefile | 8 +- .../asta-preview/skills/analyze-data/SKILL.md | 10 +-- .../asta-preview/skills/artifacts/SKILL.md | 8 +- .../skills/asta-documents/SKILL.md | 8 +- .../skills/autodiscovery/SKILL.md | 9 +-- .../asta-preview/skills/experiment/SKILL.md | 8 +- .../skills/find-literature/SKILL.md | 9 +-- .../skills/generate-theories/SKILL.md | 10 +-- .../skills/literature-report/SKILL.md | 7 +- .../skills/local-paper-index/SKILL.md | 19 +---- .../skills/pdf-extraction/SKILL.md | 10 +-- plugins/asta-preview/skills/preview/SKILL.md | 9 +-- .../skills/research-step/SKILL.md | 11 +-- .../skills/semantic-scholar/SKILL.md | 5 +- .../asta-preview/skills/workspace/SKILL.md | 2 +- plugins/asta/skills/asta-documents/SKILL.md | 8 +- .../asta/skills/literature-report/SKILL.md | 7 +- plugins/asta/skills/preview/SKILL.md | 9 +-- plugins/asta/skills/research-step/SKILL.md | 11 +-- plugins/asta/skills/semantic-scholar/SKILL.md | 5 +- plugins/asta/skills/workspace/SKILL.md | 2 +- scripts/validate-skills.py | 81 +++++++++++++++++++ skills/analyze-data/SKILL.md | 10 +-- skills/artifacts/SKILL.md | 8 +- skills/asta-documents/SKILL.md | 8 +- skills/autodiscovery/SKILL.md | 9 +-- skills/experiment/SKILL.md | 8 +- skills/find-literature/SKILL.md | 9 +-- skills/generate-theories/SKILL.md | 10 +-- skills/literature-report/SKILL.md | 7 +- skills/local-paper-index/SKILL.md | 19 +---- skills/pdf-extraction/SKILL.md | 10 +-- skills/preview/SKILL.md | 9 +-- skills/research-step/SKILL.md | 11 +-- skills/semantic-scholar/SKILL.md | 5 +- skills/workspace/SKILL.md | 2 +- 37 files changed, 152 insertions(+), 232 deletions(-) create mode 100755 scripts/validate-skills.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 63d9c82..9a727dd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,6 +29,9 @@ jobs: - name: Check plugins run: make check-plugins + - name: Check skill frontmatter against Agent Skills spec + run: make check-skills + test: runs-on: ubuntu-latest strategy: diff --git a/Makefile b/Makefile index f38b9e5..9870ed6 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help install test test-unit test-integration test-coverage lint format format-check clean build build-plugins publish publish-test push-version-tag version set-version check-plugins docker docker-test docker-test-skills docker-claude-asta docker-claude-asta-preview docker-codex-asta docker-codex-asta-preview +.PHONY: help install test test-unit test-integration test-coverage lint format format-check clean build build-plugins publish publish-test push-version-tag version set-version check-plugins check-skills docker docker-test docker-test-skills docker-claude-asta docker-claude-asta-preview docker-codex-asta docker-codex-asta-preview # Default target help: @@ -97,6 +97,10 @@ check-plugins: fi @echo "plugins/ is up to date" +# Validate every SKILL.md against the Agent Skills spec (used in CI) +check-skills: + @uvx --with pyyaml python scripts/validate-skills.py + # Build distribution packages build: clean uv build @@ -180,5 +184,5 @@ check: format-check lint test-unit @echo "All checks passed!" # Full CI check -ci: format-check lint test check-plugins +ci: format-check lint test check-plugins check-skills @echo "Full CI checks passed!" diff --git a/plugins/asta-preview/skills/analyze-data/SKILL.md b/plugins/asta-preview/skills/analyze-data/SKILL.md index 0133791..76f90e2 100644 --- a/plugins/asta-preview/skills/analyze-data/SKILL.md +++ b/plugins/asta-preview/skills/analyze-data/SKILL.md @@ -1,15 +1,9 @@ --- -name: Data Analysis +name: analyze-data description: This skill should be used when the user asks to "analyze this dataset", "run datavoyager", "run data voyager", "explore this data", "what's in this CSV", "statistical analysis of", "find patterns in", or wants an AI-driven, code-executing analysis of a tabular dataset that answers a specific research question. metadata: internal: true -allowed-tools: - - Bash(asta auth login) - - Bash(asta auth status) - - Bash(asta analyze-data *) - - Bash(asta artifacts *) - - Bash(asta documents *) - - Bash(open *) +allowed-tools: Bash(asta auth login) Bash(asta auth status) Bash(asta analyze-data *) Bash(asta artifacts *) Bash(asta documents *) Bash(open *) --- # Data Analysis diff --git a/plugins/asta-preview/skills/artifacts/SKILL.md b/plugins/asta-preview/skills/artifacts/SKILL.md index 200ac46..3b4d72f 100644 --- a/plugins/asta-preview/skills/artifacts/SKILL.md +++ b/plugins/asta-preview/skills/artifacts/SKILL.md @@ -1,13 +1,9 @@ --- -name: Asta Artifacts +name: artifacts description: Use this skill when the user asks to view, export, or open agent output artifacts — "show me the artifacts", "export the results", "open the report", "convert the task output to HTML", "what did the agent produce", or wants to work with structured outputs from an A2A agent task. metadata: internal: true -allowed-tools: - - Bash(asta * task *) - - Bash(asta artifacts *) - - Bash(asta documents *) - - Bash(open *) +allowed-tools: Bash(asta * task *) Bash(asta artifacts *) Bash(asta documents *) Bash(open *) --- # Asta Artifacts diff --git a/plugins/asta-preview/skills/asta-documents/SKILL.md b/plugins/asta-preview/skills/asta-documents/SKILL.md index da350e1..3668899 100644 --- a/plugins/asta-preview/skills/asta-documents/SKILL.md +++ b/plugins/asta-preview/skills/asta-documents/SKILL.md @@ -1,12 +1,8 @@ --- -name: Asta Library +name: asta-documents description: Local document metadata index for files used by Asta skills and tools. Use this skill when the user asks to store a document "in Asta" or retrieve "from Asta". Use it when the user references an "Asta document" or anything with an `asta://` URI. -allowed-tools: - - Bash(asta documents *) - - Read(*) - - TaskOutput - - Write(.asta/*) +allowed-tools: Bash(asta documents *) Read(*) TaskOutput Write(.asta/*) --- # Asta Documents Management diff --git a/plugins/asta-preview/skills/autodiscovery/SKILL.md b/plugins/asta-preview/skills/autodiscovery/SKILL.md index 2a8f36c..1675882 100644 --- a/plugins/asta-preview/skills/autodiscovery/SKILL.md +++ b/plugins/asta-preview/skills/autodiscovery/SKILL.md @@ -1,14 +1,9 @@ --- -name: AutoDiscovery +name: autodiscovery description: Create, configure, and monitor AutoDiscovery runs. Use when the user asks about their runs, experiments, discoveries, wants to check status, or wants to start a new discovery run. metadata: internal: true -allowed-tools: - - Bash(asta autodiscovery *) - - Bash(asta auth *) - - Read(*) - - Write(*.json) - - TaskOutput +allowed-tools: Bash(asta autodiscovery *) Bash(asta auth *) Read(*) Write(*.json) TaskOutput --- # AutoDiscovery diff --git a/plugins/asta-preview/skills/experiment/SKILL.md b/plugins/asta-preview/skills/experiment/SKILL.md index 2d409c2..374e74a 100644 --- a/plugins/asta-preview/skills/experiment/SKILL.md +++ b/plugins/asta-preview/skills/experiment/SKILL.md @@ -1,13 +1,9 @@ --- -name: Asta Software Experiment Runner +name: experiment description: Run scientific (software) experiments. Use when the user asks to "run an experiment", "run an investigation", or "research with Asta." Also use this skill to analyze experimental data generate a research report from it. The user may refer to this system by its internal project name, "Panda." metadata: internal: true -allowed-tools: - - Bash(asta experiment *) - - Bash(mkdir -p .asta/experiment/*) - - Read(.asta/experiment/*) - - TaskOutput +allowed-tools: Bash(asta experiment *) Bash(mkdir -p .asta/experiment/*) Read(.asta/experiment/*) TaskOutput --- # Run Experiments diff --git a/plugins/asta-preview/skills/find-literature/SKILL.md b/plugins/asta-preview/skills/find-literature/SKILL.md index 86b8c79..997b11b 100644 --- a/plugins/asta-preview/skills/find-literature/SKILL.md +++ b/plugins/asta-preview/skills/find-literature/SKILL.md @@ -1,14 +1,9 @@ --- -name: Asta Literature Search +name: find-literature description: This skill should be used when the user asks to "find papers", "search for papers", "what does the literature say", "find research on", "academic papers about", "literature review", "cite papers", or needs to answer questions using academic literature. metadata: internal: true -allowed-tools: - - Bash(asta literature find *) - - Bash(asta literature interactive *) - - Bash(asta papers *) - - TaskOutput - - Bash(jq *) +allowed-tools: Bash(asta literature find *) Bash(asta literature interactive *) Bash(asta papers *) TaskOutput Bash(jq *) --- # Find Literature diff --git a/plugins/asta-preview/skills/generate-theories/SKILL.md b/plugins/asta-preview/skills/generate-theories/SKILL.md index b6fe891..4ad5052 100644 --- a/plugins/asta-preview/skills/generate-theories/SKILL.md +++ b/plugins/asta-preview/skills/generate-theories/SKILL.md @@ -1,15 +1,9 @@ --- -name: Generate Theories +name: generate-theories description: This skill should be used when the user asks to "generate theories", "theorize about", "what theories explain", "form scientific theories", "literature-driven theories", "hypothesize", "form hypotheses", "generate hypotheses", "what hypotheses explain", "run the theorizer", or wants AI-generated, literature-grounded scientific theories or hypotheses about a research question. metadata: internal: true -allowed-tools: - - Bash(asta auth login) - - Bash(asta auth status) - - Bash(asta generate-theories *) - - Bash(asta artifacts *) - - Bash(asta documents *) - - Bash(open *) +allowed-tools: Bash(asta auth login) Bash(asta auth status) Bash(asta generate-theories *) Bash(asta artifacts *) Bash(asta documents *) Bash(open *) --- # Generate Theories diff --git a/plugins/asta-preview/skills/literature-report/SKILL.md b/plugins/asta-preview/skills/literature-report/SKILL.md index 141a2d4..76387ea 100644 --- a/plugins/asta-preview/skills/literature-report/SKILL.md +++ b/plugins/asta-preview/skills/literature-report/SKILL.md @@ -1,10 +1,7 @@ --- -name: Asta Literature Reports +name: literature-report description: Create or update literature reviews/reports. Use whenever you need to research, summarize, or synthesize the literature. -allowed-tools: - - Read(.asta/literature/*) - - TaskOutput - - Bash(jq *) +allowed-tools: Read(.asta/literature/*) TaskOutput Bash(jq *) --- # Literature Reports diff --git a/plugins/asta-preview/skills/local-paper-index/SKILL.md b/plugins/asta-preview/skills/local-paper-index/SKILL.md index 94050b8..a5c2d13 100644 --- a/plugins/asta-preview/skills/local-paper-index/SKILL.md +++ b/plugins/asta-preview/skills/local-paper-index/SKILL.md @@ -1,24 +1,9 @@ --- -name: Local PDF Index Builder +name: local-paper-index description: Build a searchable Asta document index from a collection of local PDF files. Use when the user asks to "index these PDFs", "put these PDFs into an Asta index", "index these PDFs using Asta", "build a local paper index", "make these PDFs searchable", or "create an index from these papers". metadata: internal: true -allowed-tools: - - Bash(asta pdf-extraction *) - - Bash(asta documents *) - - Bash(python3 *) - - Bash(bash *) - - Bash(find *) - - Bash(ls *) - - Bash(wc *) - - Bash(du *) - - Bash(mv *) - - Bash(cp *) - - Bash(cat *) - - Bash(mkdir *) - - Read(*) - - Write(*) - - Glob(*) +allowed-tools: Bash(asta pdf-extraction *) Bash(asta documents *) Bash(python3 *) Bash(bash *) Bash(find *) Bash(ls *) Bash(wc *) Bash(du *) Bash(mv *) Bash(cp *) Bash(cat *) Bash(mkdir *) Read(*) Write(*) Glob(*) --- # Local PDF Index Builder diff --git a/plugins/asta-preview/skills/pdf-extraction/SKILL.md b/plugins/asta-preview/skills/pdf-extraction/SKILL.md index 29a45e7..bc84f2f 100644 --- a/plugins/asta-preview/skills/pdf-extraction/SKILL.md +++ b/plugins/asta-preview/skills/pdf-extraction/SKILL.md @@ -1,15 +1,9 @@ --- -name: PDF Text Extraction +name: pdf-extraction description: Extract text from PDFs using olmOCR or remote OCR. Use when user asks to "extract text from PDF", "OCR a document", "read a PDF", or needs to process scanned documents. metadata: internal: true -allowed-tools: - - Bash(asta pdf-extraction *) - - Read(.asta/documents/*) - - Write(.asta/documents/*) - - Read(*/markdown/*) - - Bash(mv *) - - Bash(cp *) +allowed-tools: Bash(asta pdf-extraction *) Read(.asta/documents/*) Write(.asta/documents/*) Read(*/markdown/*) Bash(mv *) Bash(cp *) --- # PDF Text Extraction diff --git a/plugins/asta-preview/skills/preview/SKILL.md b/plugins/asta-preview/skills/preview/SKILL.md index 23d90d9..41c6b34 100644 --- a/plugins/asta-preview/skills/preview/SKILL.md +++ b/plugins/asta-preview/skills/preview/SKILL.md @@ -1,12 +1,7 @@ --- -name: Preview +name: preview description: Render and deploy project documents, reports, and notebooks. Use when docs need to be shared or when previewing how documents render with citations and formatting. -allowed-tools: - - Bash(quarto render *) - - Bash(quarto preview *) - - Bash(which quarto) - - Bash(gh run list *) - - Bash(gh run view *) +allowed-tools: Bash(quarto render *) Bash(quarto preview *) Bash(which quarto) Bash(gh run list *) Bash(gh run view *) --- # Preview diff --git a/plugins/asta-preview/skills/research-step/SKILL.md b/plugins/asta-preview/skills/research-step/SKILL.md index 10ba1af..0d2fcee 100644 --- a/plugins/asta-preview/skills/research-step/SKILL.md +++ b/plugins/asta-preview/skills/research-step/SKILL.md @@ -1,16 +1,7 @@ --- name: research-step description: Plan and execute autonomous research as a graph of typed tasks tracked in beads. Use when working from a mission.md to drive multi-step research with explicit dependencies and structured outputs. -allowed-tools: - - Bash(bd:*) - - Bash(date:*) - - Bash(scripts/*) - - Read(assets/**) - - Read(workflows/**) - - Read(scripts/**) - - Skill(asta:*) - - Skill(asta-preview:*) - - Skill(asta-plugins:*) +allowed-tools: Bash(bd:*) Bash(date:*) Bash(scripts/*) Read(assets/**) Read(workflows/**) Read(scripts/**) Skill(asta:*) Skill(asta-preview:*) Skill(asta-plugins:*) --- # Research Step diff --git a/plugins/asta-preview/skills/semantic-scholar/SKILL.md b/plugins/asta-preview/skills/semantic-scholar/SKILL.md index 1a436f2..5571e6a 100644 --- a/plugins/asta-preview/skills/semantic-scholar/SKILL.md +++ b/plugins/asta-preview/skills/semantic-scholar/SKILL.md @@ -1,8 +1,7 @@ --- -name: Semantic Scholar Lookup +name: semantic-scholar description: This skill should be used when the user asks to "get paper details", "look up a paper", "find citations", "who cited this paper", "papers by [author]", "search for papers on [topic]", or needs quick lookups of paper metadata, citations, or author information from Semantic Scholar. Use this for fast, targeted queries (not comprehensive reports). -allowed-tools: - - Bash(asta papers *) +allowed-tools: Bash(asta papers *) --- # Semantic Scholar Lookup diff --git a/plugins/asta-preview/skills/workspace/SKILL.md b/plugins/asta-preview/skills/workspace/SKILL.md index 8138b9b..2db2184 100644 --- a/plugins/asta-preview/skills/workspace/SKILL.md +++ b/plugins/asta-preview/skills/workspace/SKILL.md @@ -1,5 +1,5 @@ --- -name: Workspace +name: workspace description: Set up a GitHub Codespaces or Dev Container environment with Asta skills installed in GitHub Copilot and Quarto pre-configured. Use when asked to set up a Codespace or devcontainer for an Asta project. --- diff --git a/plugins/asta/skills/asta-documents/SKILL.md b/plugins/asta/skills/asta-documents/SKILL.md index da350e1..3668899 100644 --- a/plugins/asta/skills/asta-documents/SKILL.md +++ b/plugins/asta/skills/asta-documents/SKILL.md @@ -1,12 +1,8 @@ --- -name: Asta Library +name: asta-documents description: Local document metadata index for files used by Asta skills and tools. Use this skill when the user asks to store a document "in Asta" or retrieve "from Asta". Use it when the user references an "Asta document" or anything with an `asta://` URI. -allowed-tools: - - Bash(asta documents *) - - Read(*) - - TaskOutput - - Write(.asta/*) +allowed-tools: Bash(asta documents *) Read(*) TaskOutput Write(.asta/*) --- # Asta Documents Management diff --git a/plugins/asta/skills/literature-report/SKILL.md b/plugins/asta/skills/literature-report/SKILL.md index 141a2d4..76387ea 100644 --- a/plugins/asta/skills/literature-report/SKILL.md +++ b/plugins/asta/skills/literature-report/SKILL.md @@ -1,10 +1,7 @@ --- -name: Asta Literature Reports +name: literature-report description: Create or update literature reviews/reports. Use whenever you need to research, summarize, or synthesize the literature. -allowed-tools: - - Read(.asta/literature/*) - - TaskOutput - - Bash(jq *) +allowed-tools: Read(.asta/literature/*) TaskOutput Bash(jq *) --- # Literature Reports diff --git a/plugins/asta/skills/preview/SKILL.md b/plugins/asta/skills/preview/SKILL.md index 23d90d9..41c6b34 100644 --- a/plugins/asta/skills/preview/SKILL.md +++ b/plugins/asta/skills/preview/SKILL.md @@ -1,12 +1,7 @@ --- -name: Preview +name: preview description: Render and deploy project documents, reports, and notebooks. Use when docs need to be shared or when previewing how documents render with citations and formatting. -allowed-tools: - - Bash(quarto render *) - - Bash(quarto preview *) - - Bash(which quarto) - - Bash(gh run list *) - - Bash(gh run view *) +allowed-tools: Bash(quarto render *) Bash(quarto preview *) Bash(which quarto) Bash(gh run list *) Bash(gh run view *) --- # Preview diff --git a/plugins/asta/skills/research-step/SKILL.md b/plugins/asta/skills/research-step/SKILL.md index 10ba1af..0d2fcee 100644 --- a/plugins/asta/skills/research-step/SKILL.md +++ b/plugins/asta/skills/research-step/SKILL.md @@ -1,16 +1,7 @@ --- name: research-step description: Plan and execute autonomous research as a graph of typed tasks tracked in beads. Use when working from a mission.md to drive multi-step research with explicit dependencies and structured outputs. -allowed-tools: - - Bash(bd:*) - - Bash(date:*) - - Bash(scripts/*) - - Read(assets/**) - - Read(workflows/**) - - Read(scripts/**) - - Skill(asta:*) - - Skill(asta-preview:*) - - Skill(asta-plugins:*) +allowed-tools: Bash(bd:*) Bash(date:*) Bash(scripts/*) Read(assets/**) Read(workflows/**) Read(scripts/**) Skill(asta:*) Skill(asta-preview:*) Skill(asta-plugins:*) --- # Research Step diff --git a/plugins/asta/skills/semantic-scholar/SKILL.md b/plugins/asta/skills/semantic-scholar/SKILL.md index 1a436f2..5571e6a 100644 --- a/plugins/asta/skills/semantic-scholar/SKILL.md +++ b/plugins/asta/skills/semantic-scholar/SKILL.md @@ -1,8 +1,7 @@ --- -name: Semantic Scholar Lookup +name: semantic-scholar description: This skill should be used when the user asks to "get paper details", "look up a paper", "find citations", "who cited this paper", "papers by [author]", "search for papers on [topic]", or needs quick lookups of paper metadata, citations, or author information from Semantic Scholar. Use this for fast, targeted queries (not comprehensive reports). -allowed-tools: - - Bash(asta papers *) +allowed-tools: Bash(asta papers *) --- # Semantic Scholar Lookup diff --git a/plugins/asta/skills/workspace/SKILL.md b/plugins/asta/skills/workspace/SKILL.md index 8138b9b..2db2184 100644 --- a/plugins/asta/skills/workspace/SKILL.md +++ b/plugins/asta/skills/workspace/SKILL.md @@ -1,5 +1,5 @@ --- -name: Workspace +name: workspace description: Set up a GitHub Codespaces or Dev Container environment with Asta skills installed in GitHub Copilot and Quarto pre-configured. Use when asked to set up a Codespace or devcontainer for an Asta project. --- diff --git a/scripts/validate-skills.py b/scripts/validate-skills.py new file mode 100755 index 0000000..4df977f --- /dev/null +++ b/scripts/validate-skills.py @@ -0,0 +1,81 @@ +#!/usr/bin/env python3 +"""Validate SKILL.md frontmatter against the Agent Skills spec. + +Checks every skills/*/SKILL.md for: +- `name`: kebab-case (`^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`), max 64, matches parent dir +- `description`: 1-1024 chars, non-empty +- `allowed-tools`: space-separated string (not a YAML list) + +See https://agentskills.io/specification. +""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +import yaml + +NAME_PATTERN = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$") +REPO_ROOT = Path(__file__).resolve().parents[1] + + +def validate(skill_md: Path) -> list[str]: + errors: list[str] = [] + raw = skill_md.read_text() + if not raw.startswith("---\n"): + return [f"{skill_md}: missing YAML frontmatter"] + try: + end = raw.index("\n---\n", 4) + except ValueError: + return [f"{skill_md}: unterminated frontmatter"] + fm = yaml.safe_load(raw[4:end]) or {} + + name = fm.get("name") + if not isinstance(name, str): + errors.append(f"{skill_md}: `name` missing or not a string") + else: + if len(name) > 64 or not NAME_PATTERN.match(name): + errors.append( + f"{skill_md}: `name` {name!r} must be kebab-case " + "(`^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`, max 64)" + ) + if name != skill_md.parent.name: + errors.append( + f"{skill_md}: `name` {name!r} must match parent dir " + f"{skill_md.parent.name!r}" + ) + + desc = fm.get("description") + if not isinstance(desc, str) or not desc: + errors.append(f"{skill_md}: `description` missing or empty") + elif len(desc) > 1024: + errors.append(f"{skill_md}: `description` exceeds 1024 chars ({len(desc)})") + + allowed_tools = fm.get("allowed-tools") + if allowed_tools is not None and not isinstance(allowed_tools, str): + errors.append( + f"{skill_md}: `allowed-tools` must be a space-separated string, " + f"got {type(allowed_tools).__name__}" + ) + + return errors + + +def main() -> int: + skills_root = REPO_ROOT / "skills" + errors: list[str] = [] + for skill_md in sorted(skills_root.glob("*/SKILL.md")): + errors.extend(validate(skill_md)) + if errors: + for e in errors: + print(e, file=sys.stderr) + print(f"\n{len(errors)} validation error(s)", file=sys.stderr) + return 1 + print(f"All {len(list(skills_root.glob('*/SKILL.md')))} SKILL.md files valid.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/skills/analyze-data/SKILL.md b/skills/analyze-data/SKILL.md index 0133791..76f90e2 100644 --- a/skills/analyze-data/SKILL.md +++ b/skills/analyze-data/SKILL.md @@ -1,15 +1,9 @@ --- -name: Data Analysis +name: analyze-data description: This skill should be used when the user asks to "analyze this dataset", "run datavoyager", "run data voyager", "explore this data", "what's in this CSV", "statistical analysis of", "find patterns in", or wants an AI-driven, code-executing analysis of a tabular dataset that answers a specific research question. metadata: internal: true -allowed-tools: - - Bash(asta auth login) - - Bash(asta auth status) - - Bash(asta analyze-data *) - - Bash(asta artifacts *) - - Bash(asta documents *) - - Bash(open *) +allowed-tools: Bash(asta auth login) Bash(asta auth status) Bash(asta analyze-data *) Bash(asta artifacts *) Bash(asta documents *) Bash(open *) --- # Data Analysis diff --git a/skills/artifacts/SKILL.md b/skills/artifacts/SKILL.md index 200ac46..3b4d72f 100644 --- a/skills/artifacts/SKILL.md +++ b/skills/artifacts/SKILL.md @@ -1,13 +1,9 @@ --- -name: Asta Artifacts +name: artifacts description: Use this skill when the user asks to view, export, or open agent output artifacts — "show me the artifacts", "export the results", "open the report", "convert the task output to HTML", "what did the agent produce", or wants to work with structured outputs from an A2A agent task. metadata: internal: true -allowed-tools: - - Bash(asta * task *) - - Bash(asta artifacts *) - - Bash(asta documents *) - - Bash(open *) +allowed-tools: Bash(asta * task *) Bash(asta artifacts *) Bash(asta documents *) Bash(open *) --- # Asta Artifacts diff --git a/skills/asta-documents/SKILL.md b/skills/asta-documents/SKILL.md index da350e1..3668899 100644 --- a/skills/asta-documents/SKILL.md +++ b/skills/asta-documents/SKILL.md @@ -1,12 +1,8 @@ --- -name: Asta Library +name: asta-documents description: Local document metadata index for files used by Asta skills and tools. Use this skill when the user asks to store a document "in Asta" or retrieve "from Asta". Use it when the user references an "Asta document" or anything with an `asta://` URI. -allowed-tools: - - Bash(asta documents *) - - Read(*) - - TaskOutput - - Write(.asta/*) +allowed-tools: Bash(asta documents *) Read(*) TaskOutput Write(.asta/*) --- # Asta Documents Management diff --git a/skills/autodiscovery/SKILL.md b/skills/autodiscovery/SKILL.md index 2a8f36c..1675882 100644 --- a/skills/autodiscovery/SKILL.md +++ b/skills/autodiscovery/SKILL.md @@ -1,14 +1,9 @@ --- -name: AutoDiscovery +name: autodiscovery description: Create, configure, and monitor AutoDiscovery runs. Use when the user asks about their runs, experiments, discoveries, wants to check status, or wants to start a new discovery run. metadata: internal: true -allowed-tools: - - Bash(asta autodiscovery *) - - Bash(asta auth *) - - Read(*) - - Write(*.json) - - TaskOutput +allowed-tools: Bash(asta autodiscovery *) Bash(asta auth *) Read(*) Write(*.json) TaskOutput --- # AutoDiscovery diff --git a/skills/experiment/SKILL.md b/skills/experiment/SKILL.md index 2d409c2..374e74a 100644 --- a/skills/experiment/SKILL.md +++ b/skills/experiment/SKILL.md @@ -1,13 +1,9 @@ --- -name: Asta Software Experiment Runner +name: experiment description: Run scientific (software) experiments. Use when the user asks to "run an experiment", "run an investigation", or "research with Asta." Also use this skill to analyze experimental data generate a research report from it. The user may refer to this system by its internal project name, "Panda." metadata: internal: true -allowed-tools: - - Bash(asta experiment *) - - Bash(mkdir -p .asta/experiment/*) - - Read(.asta/experiment/*) - - TaskOutput +allowed-tools: Bash(asta experiment *) Bash(mkdir -p .asta/experiment/*) Read(.asta/experiment/*) TaskOutput --- # Run Experiments diff --git a/skills/find-literature/SKILL.md b/skills/find-literature/SKILL.md index 86b8c79..997b11b 100644 --- a/skills/find-literature/SKILL.md +++ b/skills/find-literature/SKILL.md @@ -1,14 +1,9 @@ --- -name: Asta Literature Search +name: find-literature description: This skill should be used when the user asks to "find papers", "search for papers", "what does the literature say", "find research on", "academic papers about", "literature review", "cite papers", or needs to answer questions using academic literature. metadata: internal: true -allowed-tools: - - Bash(asta literature find *) - - Bash(asta literature interactive *) - - Bash(asta papers *) - - TaskOutput - - Bash(jq *) +allowed-tools: Bash(asta literature find *) Bash(asta literature interactive *) Bash(asta papers *) TaskOutput Bash(jq *) --- # Find Literature diff --git a/skills/generate-theories/SKILL.md b/skills/generate-theories/SKILL.md index b6fe891..4ad5052 100644 --- a/skills/generate-theories/SKILL.md +++ b/skills/generate-theories/SKILL.md @@ -1,15 +1,9 @@ --- -name: Generate Theories +name: generate-theories description: This skill should be used when the user asks to "generate theories", "theorize about", "what theories explain", "form scientific theories", "literature-driven theories", "hypothesize", "form hypotheses", "generate hypotheses", "what hypotheses explain", "run the theorizer", or wants AI-generated, literature-grounded scientific theories or hypotheses about a research question. metadata: internal: true -allowed-tools: - - Bash(asta auth login) - - Bash(asta auth status) - - Bash(asta generate-theories *) - - Bash(asta artifacts *) - - Bash(asta documents *) - - Bash(open *) +allowed-tools: Bash(asta auth login) Bash(asta auth status) Bash(asta generate-theories *) Bash(asta artifacts *) Bash(asta documents *) Bash(open *) --- # Generate Theories diff --git a/skills/literature-report/SKILL.md b/skills/literature-report/SKILL.md index 141a2d4..76387ea 100644 --- a/skills/literature-report/SKILL.md +++ b/skills/literature-report/SKILL.md @@ -1,10 +1,7 @@ --- -name: Asta Literature Reports +name: literature-report description: Create or update literature reviews/reports. Use whenever you need to research, summarize, or synthesize the literature. -allowed-tools: - - Read(.asta/literature/*) - - TaskOutput - - Bash(jq *) +allowed-tools: Read(.asta/literature/*) TaskOutput Bash(jq *) --- # Literature Reports diff --git a/skills/local-paper-index/SKILL.md b/skills/local-paper-index/SKILL.md index 94050b8..a5c2d13 100644 --- a/skills/local-paper-index/SKILL.md +++ b/skills/local-paper-index/SKILL.md @@ -1,24 +1,9 @@ --- -name: Local PDF Index Builder +name: local-paper-index description: Build a searchable Asta document index from a collection of local PDF files. Use when the user asks to "index these PDFs", "put these PDFs into an Asta index", "index these PDFs using Asta", "build a local paper index", "make these PDFs searchable", or "create an index from these papers". metadata: internal: true -allowed-tools: - - Bash(asta pdf-extraction *) - - Bash(asta documents *) - - Bash(python3 *) - - Bash(bash *) - - Bash(find *) - - Bash(ls *) - - Bash(wc *) - - Bash(du *) - - Bash(mv *) - - Bash(cp *) - - Bash(cat *) - - Bash(mkdir *) - - Read(*) - - Write(*) - - Glob(*) +allowed-tools: Bash(asta pdf-extraction *) Bash(asta documents *) Bash(python3 *) Bash(bash *) Bash(find *) Bash(ls *) Bash(wc *) Bash(du *) Bash(mv *) Bash(cp *) Bash(cat *) Bash(mkdir *) Read(*) Write(*) Glob(*) --- # Local PDF Index Builder diff --git a/skills/pdf-extraction/SKILL.md b/skills/pdf-extraction/SKILL.md index 29a45e7..bc84f2f 100644 --- a/skills/pdf-extraction/SKILL.md +++ b/skills/pdf-extraction/SKILL.md @@ -1,15 +1,9 @@ --- -name: PDF Text Extraction +name: pdf-extraction description: Extract text from PDFs using olmOCR or remote OCR. Use when user asks to "extract text from PDF", "OCR a document", "read a PDF", or needs to process scanned documents. metadata: internal: true -allowed-tools: - - Bash(asta pdf-extraction *) - - Read(.asta/documents/*) - - Write(.asta/documents/*) - - Read(*/markdown/*) - - Bash(mv *) - - Bash(cp *) +allowed-tools: Bash(asta pdf-extraction *) Read(.asta/documents/*) Write(.asta/documents/*) Read(*/markdown/*) Bash(mv *) Bash(cp *) --- # PDF Text Extraction diff --git a/skills/preview/SKILL.md b/skills/preview/SKILL.md index 23d90d9..41c6b34 100644 --- a/skills/preview/SKILL.md +++ b/skills/preview/SKILL.md @@ -1,12 +1,7 @@ --- -name: Preview +name: preview description: Render and deploy project documents, reports, and notebooks. Use when docs need to be shared or when previewing how documents render with citations and formatting. -allowed-tools: - - Bash(quarto render *) - - Bash(quarto preview *) - - Bash(which quarto) - - Bash(gh run list *) - - Bash(gh run view *) +allowed-tools: Bash(quarto render *) Bash(quarto preview *) Bash(which quarto) Bash(gh run list *) Bash(gh run view *) --- # Preview diff --git a/skills/research-step/SKILL.md b/skills/research-step/SKILL.md index 10ba1af..0d2fcee 100644 --- a/skills/research-step/SKILL.md +++ b/skills/research-step/SKILL.md @@ -1,16 +1,7 @@ --- name: research-step description: Plan and execute autonomous research as a graph of typed tasks tracked in beads. Use when working from a mission.md to drive multi-step research with explicit dependencies and structured outputs. -allowed-tools: - - Bash(bd:*) - - Bash(date:*) - - Bash(scripts/*) - - Read(assets/**) - - Read(workflows/**) - - Read(scripts/**) - - Skill(asta:*) - - Skill(asta-preview:*) - - Skill(asta-plugins:*) +allowed-tools: Bash(bd:*) Bash(date:*) Bash(scripts/*) Read(assets/**) Read(workflows/**) Read(scripts/**) Skill(asta:*) Skill(asta-preview:*) Skill(asta-plugins:*) --- # Research Step diff --git a/skills/semantic-scholar/SKILL.md b/skills/semantic-scholar/SKILL.md index 1a436f2..5571e6a 100644 --- a/skills/semantic-scholar/SKILL.md +++ b/skills/semantic-scholar/SKILL.md @@ -1,8 +1,7 @@ --- -name: Semantic Scholar Lookup +name: semantic-scholar description: This skill should be used when the user asks to "get paper details", "look up a paper", "find citations", "who cited this paper", "papers by [author]", "search for papers on [topic]", or needs quick lookups of paper metadata, citations, or author information from Semantic Scholar. Use this for fast, targeted queries (not comprehensive reports). -allowed-tools: - - Bash(asta papers *) +allowed-tools: Bash(asta papers *) --- # Semantic Scholar Lookup diff --git a/skills/workspace/SKILL.md b/skills/workspace/SKILL.md index 8138b9b..2db2184 100644 --- a/skills/workspace/SKILL.md +++ b/skills/workspace/SKILL.md @@ -1,5 +1,5 @@ --- -name: Workspace +name: workspace description: Set up a GitHub Codespaces or Dev Container environment with Asta skills installed in GitHub Copilot and Quarto pre-configured. Use when asked to set up a Codespace or devcontainer for an Asta project. ---