feat(skills): add skills infrastructure and shared skill by moonming · Pull Request #1 · api7/a6

moonming · 2026-03-07T14:47:40Z

Summary

Add AI agent skill system with SKILL.md format, compatible with 39+ AI coding agents (Claude Code, OpenCode, Cursor, GitHub Copilot, Windsurf, etc.).

This PR establishes the skills infrastructure (PR-28) — the foundation for 40 skills across 9 PRs (PR-28 through PR-36).

Changes

skills/a6-shared/SKILL.md — Core shared skill covering project conventions, architecture patterns, command structure, and development workflow
scripts/validate-skills.sh — CI validation script that checks YAML frontmatter (required fields, name matches directory, kebab-case naming, non-empty description)
docs/skills.md — Skill format specification, taxonomy (shared/plugin/recipe/persona), and authoring guide
.github/workflows/ci.yml — New validate-skills CI job
Makefile — New validate-skills target
AGENTS.md — Updated project structure and document map with skills directory
docs/roadmap.md — Added Phase 4 with PR-28 through PR-36 plan

Skill Format

---
name: a6-plugin-key-auth       # Must match directory name, kebab-case
description: >-                 # Required, non-empty
  Skill for configuring key-auth plugin...
version: "1.0.0"               # Recommended
metadata:
  category: plugin              # shared | plugin | recipe | persona
---
# Markdown body with instructions

Validation

$ make validate-skills
INFO: Validating skills/a6-shared/SKILL.md
OK: skills/a6-shared/SKILL.md: name=a6-shared
Validated 1 skill(s).
All skills valid.

Next PRs

PR	Skills Count	Description
PR-29	5	Authentication plugin skills
PR-30	4	Security + rate limiting skills
PR-31	5	Traffic + transformation skills
PR-32	5	Operational recipe skills
PR-33	4	AI Gateway skills
PR-34	6	Observability skills
PR-35	5	Advanced plugin skills
PR-36	5	Advanced recipes + personas

Add AI agent skill system with SKILL.md format compatible with 39+ AI coding agents. Includes CI validation script, the first shared skill (a6-shared), documentation, and roadmap for PR-28 through PR-36. - skills/a6-shared/SKILL.md: Core shared skill with project conventions - scripts/validate-skills.sh: CI validation for frontmatter fields - docs/skills.md: Skill format, taxonomy, and authoring guide - .github/workflows/ci.yml: Add validate-skills job - Makefile: Add validate-skills target - AGENTS.md: Add skills directory to project structure - docs/roadmap.md: Add Phase 4 (PR-28 through PR-36)

Copilot

Pull request overview

This PR introduces an AI agent “skills” system for the a6 CLI, defining a standard skills/<name>/SKILL.md format and adding CI automation to validate skill metadata as the foundation for additional skill packs.

Changes:

Added the first shared skill (skills/a6-shared/SKILL.md) describing a6 conventions, architecture patterns, and workflows.
Added a validation script (scripts/validate-skills.sh) plus Makefile/CI wiring to enforce required frontmatter fields and naming rules.
Added documentation for the skills format and expanded the roadmap to include Phase 4 (PR-28 through PR-36).

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`skills/a6-shared/SKILL.md`	Introduces the baseline shared skill content and project/layout guidance for agents.
`scripts/validate-skills.sh`	Adds CI validation logic for SKILL.md YAML frontmatter and naming rules.
`docs/skills.md`	Documents the skill taxonomy, file format, and validation rules.
`docs/roadmap.md`	Updates roadmap status and adds Phase 4 plan entries for skills.
`Makefile`	Adds `validate-skills` target to run the validation script locally.
`AGENTS.md`	Updates the document map and project tree to include skills and validation script.
`.github/workflows/ci.yml`	Adds a `validate-skills` CI job running the validation script.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Copilot · 2026-03-07T14:52:34Z

+    # Extract 'name' field from frontmatter
+    # Handles: name: value, name: "value", name: 'value'
+    name=$(echo "$frontmatter" | grep -E '^name:' | head -1 | sed 's/^name:[[:space:]]*//' | sed 's/^["'\'']//' | sed 's/["'\'']$//' | tr -d '\r')
+
+    if [ -z "$name" ]; then
+        log_error "$rel_path: missing required field 'name'"
+        continue
+    fi


With set -euo pipefail, the name=$(...) pipeline will cause the script to exit early when grep -E '^name:' finds no match (exit status 1), so the subsequent if [ -z "$name" ] error reporting won't run and later files won't be validated. To keep validation/reporting consistent, guard the grep/pipeline so a missing name: results in an empty string instead of terminating the script.

Copilot · 2026-03-07T14:52:34Z

+    # If no errors for this file, log success
+    if [ $errors -eq 0 ] || true; then
+        log_ok "$rel_path: name=$name"
+    fi


This condition is always true because of || true, so the script will log OK even when validation errors were recorded for the current file (and even after earlier files incremented errors). Track per-file errors (e.g., snapshot errors at the start of each loop) and only emit OK when the current file introduced no new errors.

Copilot · 2026-03-07T14:52:34Z

+│   ├── ssl/                        # a6 ssl ...
+│   ├── plugin/                     # a6 plugin list|get
+│   ├── config/                     # a6 config sync|diff|dump|validate
+│   └── context/                    # a6 context create|use|list|delete|current


The pkg/cmd/ tree here lists only a subset of the command groups that exist in the repository (e.g., it omits globalrule/, pluginconfig/, pluginmetadata/, proto/, secret/, streamroute/, consumergroup/, credential/, plus non-resource groups like debug/, version/, etc.). Since this skill is meant to convey project layout, please either include the missing directories or add an explicit .../note that the list is intentionally partial.

Suggested change

│ └── context/ # a6 context create|use|list|delete|current

│ ├── context/ # a6 context create|use|list|delete|current

│ ├── globalrule/ # a6 globalrule ...

│ ├── pluginconfig/ # a6 pluginconfig ...

│ ├── pluginmetadata/ # a6 pluginmetadata ...

│ ├── proto/ # a6 proto ...

│ ├── secret/ # a6 secret ...

│ ├── streamroute/ # a6 streamroute ...

│ ├── consumergroup/ # a6 consumergroup ...

│ ├── credential/ # a6 credential ...

│ ├── debug/ # non-resource debug commands

│ ├── version/ # non-resource version command

│ └── ... # other command groups omitted for brevity

Copilot · 2026-03-07T14:52:34Z

+    # Extract frontmatter (content between first two --- lines)
+    frontmatter=$(awk '/^---$/{if(++n==2)exit}n==1{print}' "$skill_file")
+
+    if [ -z "$frontmatter" ]; then
+        log_error "$rel_path: no YAML frontmatter found (must start with --- and end with ---)"
+        continue


The frontmatter extraction grabs the content between the first two lines that equal --- anywhere in the file. This means a SKILL.md that doesn't start with frontmatter (but contains a Markdown --- horizontal rule later) could be mis-parsed as having frontmatter. Consider explicitly requiring the first non-empty line to be --- (and erroring otherwise) so validation matches the documented format.

Copilot AI review requested due to automatic review settings March 7, 2026 14:47

Copilot started reviewing on behalf of moonming March 7, 2026 14:48 View session

moonming merged commit c0f30c7 into main Mar 7, 2026
6 checks passed

Copilot AI reviewed Mar 7, 2026

View reviewed changes

This was referenced May 26, 2026

a6 GA Readiness #33

Closed

Docs hygiene: refresh roadmap, conditional-plugin notes, entry points #45

Closed

Define a6 GA scope and supported-version matrix #49

Closed

docs: bug-class audit, UX sweep, roadmap refresh, user-guide entry points #52

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(skills): add skills infrastructure and shared skill#1

feat(skills): add skills infrastructure and shared skill#1
moonming merged 1 commit into
mainfrom
feat/skills-infra

moonming commented Mar 7, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-│   └── context/                    # a6 context create|use|list|delete|current
+│   ├── context/                    # a6 context create|use|list|delete|current
+│   ├── globalrule/                 # a6 globalrule ...
+│   ├── pluginconfig/               # a6 pluginconfig ...
+│   ├── pluginmetadata/             # a6 pluginmetadata ...
+│   ├── proto/                      # a6 proto ...
+│   ├── secret/                     # a6 secret ...
+│   ├── streamroute/                # a6 streamroute ...
+│   ├── consumergroup/              # a6 consumergroup ...
+│   ├── credential/                 # a6 credential ...
+│   ├── debug/                      # non-resource debug commands
+│   ├── version/                    # non-resource version command
+│   └── ...                         # other command groups omitted for brevity

Conversation

moonming commented Mar 7, 2026

Summary

Changes

Skill Format

Validation

Next PRs

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants