docs(skill): add skill YAML schema and examples

examples/skills/composed.yaml

@@ -0,0 +1,31 @@
+# Composed skill example — includes other skills and adds own tools
+# Register: agents skill add --config composed.yaml
+
+name: local/git-github
+description: "Git operations and GitHub integration"
+
+tools:
+  - name: builtin/git_status
+  - name: builtin/git_diff
+  - name: builtin/git_log
+  - name: builtin/git_blame
+
+includes:
+  - name: local/file-reader
+
+mcp_servers:
+  - name: github
+    transport: stdio
+    command: npx
+    args:
+      - "-y"
+      - "@modelcontextprotocol/server-github"
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
+    tool_filter:
+      include:
+        - create_issue
+        - create_pull_request
+        - list_repos
+        - get_file_contents
+

examples/skills/inline-tool.yaml

@@ -0,0 +1,37 @@
+# Inline-tool skill example — self-contained tools defined inline
+# Register: agents skill add --config inline-tool.yaml
+
+name: local/text-processing
+description: "Simple text transformation utilities"
+
+inline_tools:
+  - name: word_count
+    description: "Count words in text"
+    source: custom
+    code: |
+      def run(input_data):
+          text = input_data.get("text", "")
+          return {"count": len(text.split())}
+    input_schema:
+      type: object
+      properties:
+        text:
+          type: string
+          description: "Text to count words in"
+      required: ["text"]
+    writes: false
+
+  - name: to_uppercase
+    description: "Convert text to uppercase"
+    source: custom
+    code: |
+      def run(input_data):
+          return {"result": input_data.get("text", "").upper()}
+    input_schema:
+      type: object
+      properties:
+        text:
+          type: string
+      required: ["text"]
+    writes: false
+

examples/skills/mcp-backed.yaml

@@ -0,0 +1,23 @@
+# MCP-backed skill example — tools served via MCP server
+# Register: agents skill add --config mcp-backed.yaml
+
+name: local/linear-tracker
+description: "Linear issue tracking integration via MCP"
+
+mcp_servers:
+  - name: linear
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-linear"]
+    env:
+      LINEAR_API_KEY: "${LINEAR_API_KEY}"
+
+  - name: sentry
+    transport: sse
+    url: "https://mcp.sentry.dev/sse"
+    headers:
+      Authorization: "Bearer ${SENTRY_TOKEN}"
+    tool_filter:
+      exclude:
+        - delete_project
+

examples/skills/single-tool.yaml

@@ -0,0 +1,11 @@
+# Single-tool skill example
+# Register: agents skill add --config single-tool.yaml
+
+name: local/file-reader
+description: "Basic file reading operations"
+
+tools:
+  - name: builtin/read_file
+  - name: builtin/list_directory
+  - name: builtin/search_files
+

examples/skills/validation-only.yaml

@@ -0,0 +1,5 @@
+# Minimal skill example — name-only (all other fields optional per spec)
+# Register: agents skill add --config validation-only.yaml
+
+name: local/empty-skill
+