Bring bundled skill frontmatter into Agent Skills spec compliance

.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:

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!"

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

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

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

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
 

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
 

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

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

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

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

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

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

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

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

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.
 ---
 

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

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

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

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

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

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.
 ---