diff --git a/README.md b/README.md index 7a78bad..0ad27e6 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ This tool collects context from predefined rule files and a task-specific prompt - **Dynamic Context Assembly**: Merges context from various source files. - **Task-Specific Prompts**: Use different prompts for different tasks (e.g., `feature`, `bugfix`). - **Rule-Based Context**: Define reusable context snippets (rules) that can be included or excluded. +- **Skills System**: Progressive disclosure of specialized capabilities via skill directories. - **Frontmatter Filtering**: Select rules based on metadata using frontmatter selectors (matches top-level YAML fields only). - **Bootstrap Scripts**: Run scripts to fetch or generate context dynamically. - **Parameter Substitution**: Inject values into your task prompts. @@ -211,6 +212,9 @@ The tool looks for task and rule files in the following locations, in order of p - `./.cursor/commands/*.md` - `./.opencode/command/*.md` +**Skills** (specialized capabilities with progressive disclosure): +- `./.agents/skills/*/SKILL.md` (each subdirectory in `.agents/skills/` can contain a `SKILL.md` file) + **Rules:** The tool searches for a variety of files and directories, including: - `CLAUDE.local.md` @@ -505,6 +509,24 @@ languages: If you need to filter on nested data, flatten your frontmatter structure to use top-level fields only. +**MCP Server Configuration** + +Rules can optionally specify MCP (Model Context Protocol) server configurations for integration with AI coding agents. This is useful for defining server processes that AI agents can interact with. + +```yaml +--- +languages: + - python +mcp_server: + command: python + args: ["-m", "server"] + env: + PYTHON_PATH: /usr/bin/python3 +--- +``` + +For detailed information on MCP server configuration, see the [File Formats Reference](https://kitproj.github.io/coding-context-cli/reference/file-formats#mcp_server-rule-metadata). + ### Targeting a Specific Agent The `-a` flag specifies which AI coding agent you're using. This information is currently used for: @@ -614,6 +636,73 @@ Commands can also receive inline parameters: /deploy env="production" version="1.2.3" ``` +### Skill Files + +Skill files provide specialized capabilities with progressive disclosure. Skills are discovered in `.agents/skills/` directories and each skill is a subdirectory containing a `SKILL.md` file with metadata. + +**Skills enable:** +- **Progressive Disclosure**: Only skill metadata (name, description) is included in the initial context +- **On-Demand Loading**: AI agents can load full skill content when needed +- **Modular Capabilities**: Organize domain-specific knowledge separately from general rules +- **Selector Filtering**: Skills can be filtered using selectors just like rules + +**Example skill structure:** +``` +.agents/skills/ +├── data-analysis/ +│ └── SKILL.md +└── pdf-processing/ + └── SKILL.md +``` + +**Example skill file (`.agents/skills/data-analysis/SKILL.md`):** +```markdown +--- +name: data-analysis +description: Analyze datasets, generate charts, and create summary reports. Use when the user needs to work with CSV, Excel, or other tabular data formats. +license: MIT +metadata: + author: team-name + version: "1.0" +--- + +# Data Analysis + +## When to use this skill +Use this skill when the user needs to: +- Analyze CSV or Excel files +- Generate charts and visualizations +- Calculate statistics and summaries + +## How to analyze data +1. Use pandas for data analysis: + ```python + import pandas as pd + df = pd.read_csv('data.csv') + ``` +``` + +**Skill Frontmatter Fields:** +- `name` (required): Skill identifier, 1-64 characters +- `description` (required): What the skill does and when to use it, 1-1024 characters +- `license` (optional): License applied to the skill +- `compatibility` (optional): Environment requirements, max 500 characters +- `metadata` (optional): Arbitrary key-value pairs + +**XML Output:** +Skills are output as XML for easy parsing by AI agents: +```xml + + + data-analysis + Analyze datasets, generate charts... + /path/to/.agents/skills/data-analysis/SKILL.md + + +``` + +The AI agent can then read the full skill content from the provided location when needed. + ### Task Frontmatter Task frontmatter is **always** automatically included at the beginning of the output when a task file has frontmatter. This allows the AI agent or downstream tool to access metadata about the task being executed. There is no flag needed to enable this - it happens automatically. diff --git a/docs/how-to/create-skills.md b/docs/how-to/create-skills.md new file mode 100644 index 0000000..e0ef17a --- /dev/null +++ b/docs/how-to/create-skills.md @@ -0,0 +1,400 @@ +--- +layout: default +title: Create Skills +parent: How-To Guides +nav_order: 4 +--- + +# How to Create Skills + +Skills provide specialized capabilities with progressive disclosure. This guide shows you how to create and organize skills for your AI agents. + +## What are Skills? + +Skills are modular, specialized capabilities that: +- Provide domain-specific knowledge and workflows +- Use progressive disclosure to minimize token usage +- Can be loaded on-demand by AI agents +- Are organized in subdirectories for easy management + +## Basic Skill Structure + +Each skill is a subdirectory in `.agents/skills/` containing a `SKILL.md` file: + +``` +.agents/skills/ +├── data-analysis/ +│ └── SKILL.md +├── pdf-processing/ +│ └── SKILL.md +└── api-testing/ + └── SKILL.md +``` + +## Creating Your First Skill + +### Step 1: Create the Skill Directory + +```bash +mkdir -p .agents/skills/my-skill +``` + +### Step 2: Create the SKILL.md File + +Create `.agents/skills/my-skill/SKILL.md` with frontmatter and content: + +```markdown +--- +name: my-skill +description: Brief description of what this skill does and when to use it. Keep it concise - this is shown in the initial context. +--- + +# My Skill + +## When to use this skill +Use this skill when the user needs to: +- First use case +- Second use case +- Third use case + +## How to accomplish tasks +1. Step-by-step instructions +2. Code examples +3. Best practices + +## Examples +Provide practical examples here. +``` + +### Step 3: Test the Skill + +Run a task to see your skill in the output: + +```bash +coding-context my-task +``` + +Look for the skills section in the output: +```xml + + + my-skill + Brief description... + /path/to/.agents/skills/my-skill/SKILL.md + + +``` + +## Frontmatter Fields + +### Required Fields + +#### `name` +The skill identifier. Must be 1-64 characters. + +```yaml +--- +name: data-analysis +--- +``` + +#### `description` +Explains what the skill does and when to use it. Must be 1-1024 characters. This is shown in the initial context. + +```yaml +--- +description: Analyze datasets, generate charts, and create summary reports. Use when working with CSV, Excel, or other tabular data. +--- +``` + +### Optional Fields + +#### `license` +The license applied to the skill. + +```yaml +--- +license: MIT +--- +``` + +#### `compatibility` +Environment requirements. Max 500 characters. + +```yaml +--- +compatibility: Requires Python 3.8+ with pandas and matplotlib installed +--- +``` + +#### `metadata` +Arbitrary key-value pairs for additional information. + +```yaml +--- +metadata: + author: data-team + version: "2.1" + category: analytics + tags: data,visualization,reporting +--- +``` + +## Complete Example + +Here's a complete skill for PDF processing: + +**.agents/skills/pdf-processing/SKILL.md:** +```markdown +--- +name: pdf-processing +description: Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. +license: Apache-2.0 +metadata: + author: document-team + version: "1.0" + category: document-processing +--- + +# PDF Processing + +## When to use this skill +Use this skill when the user needs to: +- Extract text or tables from PDF documents +- Fill out PDF forms programmatically +- Merge multiple PDF files into one +- Split PDF files into separate documents + +## How to extract text +1. Use pdfplumber for text extraction: + ```python + import pdfplumber + with pdfplumber.open('document.pdf') as pdf: + text = pdf.pages[0].extract_text() + print(text) + ``` + +2. For tables, use: + ```python + with pdfplumber.open('document.pdf') as pdf: + tables = pdf.pages[0].extract_tables() + ``` + +## How to fill forms +1. Use PyPDF2 to fill form fields: + ```python + from PyPDF2 import PdfReader, PdfWriter + + reader = PdfReader('form.pdf') + writer = PdfWriter() + + # Update form fields + writer.add_page(reader.pages[0]) + writer.update_page_form_field_values( + writer.pages[0], + {"field_name": "value"} + ) + + with open('filled_form.pdf', 'wb') as output: + writer.write(output) + ``` + +## How to merge documents +```python +from PyPDF2 import PdfMerger + +merger = PdfMerger() +merger.append('document1.pdf') +merger.append('document2.pdf') +merger.write('merged.pdf') +merger.close() +``` + +## Best Practices +- Always close PDF files after processing +- Handle exceptions for corrupt or password-protected PDFs +- Use pdfplumber for text extraction (better accuracy) +- Use PyPDF2 for form manipulation and merging +``` + +## Organizing Skills + +### Group Related Skills + +``` +.agents/skills/ +├── web-scraping/ +│ └── SKILL.md +├── api-testing/ +│ └── SKILL.md +└── data/ + ├── data-analysis/ + │ └── SKILL.md + └── data-visualization/ + └── SKILL.md +``` + +### Include Supporting Files + +Skills can include additional files: + +``` +.agents/skills/pdf-processing/ +├── SKILL.md +├── examples/ +│ ├── example1.py +│ └── example2.py +└── references/ + └── REFERENCE.md +``` + +Reference them in your SKILL.md: +```markdown +For more details, see [the reference guide](references/REFERENCE.md). +``` + +## Using Selectors with Skills + +Skills can be filtered using selectors, just like rules: + +```yaml +--- +name: go-testing +description: Write and run Go tests with best practices +languages: + - go +stage: testing +--- +``` + +Filter skills by selector: +```bash +# Only include Go testing skills +coding-context -s languages=go -s stage=testing implement-feature +``` + +## Progressive Disclosure Pattern + +Skills use progressive disclosure to save tokens: + +1. **Initial Context**: Only metadata (name, description, location) is included +2. **On-Demand Loading**: AI agents can read the full SKILL.md file when needed + +### How It Works + +When you run a task, the output includes: +```xml + + + pdf-processing + Extract text and tables from PDF files... + /absolute/path/to/.agents/skills/pdf-processing/SKILL.md + + +``` + +The AI agent can: +1. See available skills in the context +2. Decide which skill is relevant +3. Read the full SKILL.md file from the location when needed + +## Best Practices + +### Writing Good Descriptions + +**Good description (clear, actionable):** +```yaml +description: Analyze datasets, generate charts, and create reports. Use when working with CSV, Excel, or tabular data for analysis or visualization. +``` + +**Poor description (vague, unhelpful):** +```yaml +description: Data stuff. Use for data. +``` + +### Organizing Content + +Structure your skill content clearly: + +```markdown +# Skill Name + +## When to use this skill +- Clear use cases + +## How to accomplish tasks +- Step-by-step instructions +- Code examples +- Configuration details + +## Examples +- Practical examples +- Common scenarios + +## Best Practices +- Tips and recommendations +- Common pitfalls to avoid + +## Troubleshooting +- Common issues and solutions +``` + +### Naming Conventions + +- Use lowercase with hyphens: `data-analysis`, `pdf-processing` +- Be descriptive: `api-testing` not `api` +- Match the directory name to the skill name + +## Testing Skills + +### Verify Skill Discovery + +```bash +# Run any task and check for skills in output +coding-context my-task 2>&1 | grep -A 10 "available_skills" +``` + +### Test with Selectors + +```bash +# Verify selector filtering works +coding-context -s languages=python my-task +``` + +### Check Skill Metadata + +Ensure your skill has: +- Valid YAML frontmatter +- Required fields (name, description) +- Description length: 1-1024 characters +- Name length: 1-64 characters + +## Common Issues + +### Skill Not Appearing + +**Check:** +1. Directory structure: `.agents/skills/skill-name/SKILL.md` +2. Frontmatter is valid YAML +3. Required fields (name, description) are present +4. File is named exactly `SKILL.md` (case-sensitive) + +### Validation Errors + +**Error: "skill missing required 'name' field"** +- Add `name:` field to frontmatter + +**Error: "skill 'name' field must be 1-64 characters"** +- Shorten the skill name + +**Error: "skill missing required 'description' field"** +- Add `description:` field to frontmatter + +**Error: "skill 'description' field must be 1-1024 characters"** +- Adjust description length + +## See Also + +- [File Formats Reference](../reference/file-formats) - Detailed skill file specification +- [Search Paths Reference](../reference/search-paths) - Where skills are discovered +- [How to Use Selectors](./use-selectors) - Filtering skills with selectors diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 54765fd..aca8483 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -15,6 +15,7 @@ These guides are problem-oriented and help you achieve specific goals. - [Create Task Files](./create-tasks) - Define what AI agents should do - [Create Rule Files](./create-rules) - Provide reusable context +- [Create Skills](./create-skills) - Organize specialized capabilities with progressive disclosure - [Use Frontmatter Selectors](./use-selectors) - Filter rules and tasks - [Use Remote Directories](./use-remote-directories) - Load rules from Git, HTTP, or S3 - [Use with AI Agents](./use-with-ai-agents) - Integrate with various AI tools diff --git a/docs/index.md b/docs/index.md index f6bc387..e7f05e5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,6 +38,7 @@ Step-by-step guides to get you started: Practical guides to solve specific problems: - [Create Task Files](./how-to/create-tasks) - Define what AI agents should do - [Create Rule Files](./how-to/create-rules) - Provide reusable context +- [Create Skills](./how-to/create-skills) - Organize specialized capabilities - [Use Frontmatter Selectors](./how-to/use-selectors) - Filter rules and tasks - [Use Remote Directories](./how-to/use-remote-directories) - Load rules from Git, HTTP, or S3 - [Use with AI Agents](./how-to/use-with-ai-agents) - Integrate with various AI tools @@ -68,6 +69,7 @@ Conceptual guides to deepen your understanding: - **Remote Directories**: Load rules from Git, HTTP, S3, and other sources - **Task-Specific Prompts**: Different prompts for different tasks - **Rule-Based Context**: Reusable context snippets +- **Skills System**: Progressive disclosure of specialized capabilities - **Frontmatter Filtering**: Select rules based on metadata - **Bootstrap Scripts**: Fetch or generate context dynamically - **Parameter Substitution**: Inject runtime values diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 9cf9398..2e177e6 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -293,8 +293,14 @@ coding-context -w fix-bug # Combine with other options coding-context -a copilot -w -s languages=go -p issue=123 fix-bug + +# Resume mode with write rules: rules are skipped, only task output to stdout +coding-context -a copilot -w -r fix-bug ``` +**Note on Resume Mode:** +When using `-w` with `-r` (resume mode), no rules file is written since rules are not collected in resume mode. Only the task prompt is output to stdout. + **Use case:** This mode is particularly useful when working with AI coding agents that read rules from specific configuration files. Instead of including all rules in the prompt (consuming tokens), you can write them to the agent's config file once and only send the task prompt. @@ -309,16 +315,27 @@ This mode is particularly useful when working with AI coding agents that read ru The assembled context, consisting of: 1. Task frontmatter (YAML format) - always included when task has frontmatter -2. All matching rule files -3. The selected task prompt (with parameters substituted) +2. Available skills metadata (XML format) - included when skills are discovered +3. All matching rule files +4. The selected task prompt (with parameters substituted) Task frontmatter is automatically included at the beginning of the output when present. This includes all frontmatter fields such as `task_name`, `selectors`, `resume`, `language`, `agent`, and any custom fields. +Skills metadata (when present) is output as XML after the task frontmatter and before rules, listing available skills for progressive disclosure. + **Example output:** ```yaml --- resume: false --- + + + data-analysis + Analyze datasets and generate reports... + /path/to/.agents/skills/data-analysis/SKILL.md + + + # Rule content here... # Fix Bug Task diff --git a/docs/reference/file-formats.md b/docs/reference/file-formats.md index 97a7d68..4e1dc40 100644 --- a/docs/reference/file-formats.md +++ b/docs/reference/file-formats.md @@ -836,6 +836,174 @@ coding-context -s enabled=true task # Matches enabled: true coding-context -s languages=go task # Matches languages: [ go ] ``` +## Skill Files + +Skill files provide specialized capabilities with progressive disclosure. Each skill is a directory containing a `SKILL.md` file with frontmatter metadata and content. + +### Format + +```markdown +--- +name: skill-identifier +description: Brief description of what the skill does and when to use it +license: MIT +metadata: + author: team-name + version: "1.0" +--- + +# Skill Content + +Full skill documentation, workflows, and procedures here. +``` + +### Directory Structure + +Skills are organized in subdirectories within `.agents/skills/`: + +``` +.agents/skills/ +├── data-analysis/ +│ └── SKILL.md +├── pdf-processing/ +│ └── SKILL.md +└── api-testing/ + ├── SKILL.md + └── references/ + └── REFERENCE.md +``` + +### Frontmatter Fields + +#### `name` (required) + +**Type:** String +**Length:** 1-64 characters +**Purpose:** Unique identifier for the skill + +**Example:** +```yaml +--- +name: data-analysis +--- +``` + +#### `description` (required) + +**Type:** String +**Length:** 1-1024 characters +**Purpose:** Explains what the skill does and when to use it. This description is shown in the initial context for progressive disclosure. + +**Example:** +```yaml +--- +name: pdf-processing +description: Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. +--- +``` + +#### `license` (optional) + +**Type:** String +**Purpose:** Specifies the license applied to the skill + +**Example:** +```yaml +--- +license: Apache-2.0 +--- +``` + +#### `compatibility` (optional) + +**Type:** String +**Max Length:** 500 characters +**Purpose:** Indicates environment requirements + +**Example:** +```yaml +--- +compatibility: Requires Python 3.8+ with pandas and matplotlib installed +--- +``` + +#### `metadata` (optional) + +**Type:** Map of string key-value pairs +**Purpose:** Arbitrary metadata about the skill + +**Example:** +```yaml +--- +metadata: + author: data-team + version: "2.1" + category: analytics +--- +``` + +### Progressive Disclosure + +Skills use progressive disclosure to minimize token usage: + +1. **Initial Context**: Only skill metadata (name, description, location) is included +2. **Full Content**: AI agents can load full skill content by reading the SKILL.md file when needed + +**XML Output in Context:** +```xml + + + data-analysis + Analyze datasets, generate charts, and create summary reports... + /absolute/path/to/.agents/skills/data-analysis/SKILL.md + + + pdf-processing + Extract text and tables from PDF files... + /absolute/path/to/.agents/skills/pdf-processing/SKILL.md + + +``` + +### Selector Filtering + +Skills can be filtered using selectors in their frontmatter, just like rules: + +```yaml +--- +name: go-testing +description: Write and run Go tests with best practices +languages: + - go +stage: testing +--- +``` + +```bash +# Only include Go testing skills +coding-context -s languages=go -s stage=testing implement-feature +``` + +Skills without matching selectors are excluded from the output. + +### File Location + +Skill files must be in these directories within any search path directory: +- `.agents/skills/*/SKILL.md` (each subdirectory must contain a SKILL.md file) + +### Validation + +The CLI validates: +- ✅ `name` field is present and 1-64 characters +- ✅ `description` field is present and 1-1024 characters +- ✅ YAML frontmatter is well-formed +- ✅ Skills match selectors (if provided) + +The CLI does NOT validate: +- Skill content format or structure +- Reference links within skills +- Whether additional files in skill directory exist + ## Special Behaviors ### Multiple Tasks with Same Filename diff --git a/docs/reference/search-paths.md b/docs/reference/search-paths.md index 0ffd7c6..79f71d5 100644 --- a/docs/reference/search-paths.md +++ b/docs/reference/search-paths.md @@ -31,6 +31,23 @@ Command files are referenced via slash commands inside task content. Within each 2. `.cursor/commands/` 3. `.opencode/command/` +### Skill File Search Paths + +Skill files provide specialized capabilities with progressive disclosure. Within each directory, skill files are searched in: + +1. `.agents/skills/*/SKILL.md` (each subdirectory in `.agents/skills/` can contain a `SKILL.md` file) + +**Example:** +``` +.agents/skills/ +├── data-analysis/ +│ └── SKILL.md +├── pdf-processing/ +│ └── SKILL.md +└── api-testing/ + └── SKILL.md +``` + ### Discovery Rules - All `.md` files in these directories are examined