Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kitproj/coding-context-cli

Get the session context for a coding agent.
https://github.com/kitproj/coding-context-cli

Last synced: 5 months ago
JSON representation

Get the session context for a coding agent.

Awesome Lists containing this project

README 

          
# Coding Agent Context CLI



A command-line interface for dynamically assembling context for AI coding agents.



This tool collects context from predefined rule files and a task-specific prompt, substitutes parameters, and prints a single, combined context to standard output. This is useful for feeding a large amount of relevant information into an AI model like Claude, Gemini, or OpenAI's GPT series.



**📖 [View Full Documentation](https://kitproj.github.io/coding-context-cli/)**  

**📋 [View Specification](./SPECIFICATION.md)** - The Coding Context Standard  

**📊 [View Slide Deck](./SLIDES.md)** | [Download PDF](./SLIDES.pdf) | [How to Present](./SLIDES_README.md)



## Generated Context Structure



The tool assembles context into a structured prompt with the following components:



```

┌─────────────────────────────────────────────────────────────┐

│ Generated Coding Context Prompt                             │

├─────────────────────────────────────────────────────────────┤

│                                                               │

│  ┌───────────────────────────────────────────────────────┐  │

│  │ 1. Rules Content (Markdown)                           │  │

│  │    • Coding standards and guidelines                  │  │

│  │    • Team conventions and best practices              │  │

│  │    • Filtered by selectors (-s flag)                  │  │

│  │    • Skipped in resume mode (-r flag)                 │  │

│  └───────────────────────────────────────────────────────┘  │

│                                                               │

│  ┌───────────────────────────────────────────────────────┐  │

│  │ 2. Skills Metadata (XML) - Optional                   │  │

│  │    • Available skills with names & descriptions       │  │

│  │    • Progressive disclosure - full content on demand  │  │

│  │    • Only included if skills are discovered           │  │

│  └───────────────────────────────────────────────────────┘  │

│                                                               │

│  ┌───────────────────────────────────────────────────────┐  │

│  │ 3. Task Content (Markdown)                            │  │

│  │    • Task-specific instructions                       │  │

│  │    • Parameter substitutions (${param})               │  │

│  │    • Command expansions (!`command`)                  │  │

│  │    • Path expansions (@file)                          │  │

│  └───────────────────────────────────────────────────────┘  │

│                                                               │

└─────────────────────────────────────────────────────────────┘

```



**Key Points:**

- **Rules**: Reusable context that applies across multiple tasks

- **Skills**: Enable progressive disclosure of specialized capabilities

- **Task Content**: Specific instructions for the current task with dynamic content expansion

- **Note**: Task frontmatter is used for filtering and metadata but is not included in the output



## Features



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

- **Token Estimation**: Get an estimate of the total token count for the generated context.



## Supported Coding Agents



This tool is compatible with configuration files from various AI coding agents and IDEs. **[View complete list of 35+ supported agents →](https://kitproj.github.io/coding-context-cli/reference/supported-agents)**



### Primary Supported Agents (with dedicated `-a` flag)



- **[GitHub Copilot](https://github.com/features/copilot)**: `.github/copilot-instructions.md`, `.github/agents` (`-a copilot`)

- **[Anthropic Claude](https://claude.ai/)**: `CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md` (`-a claude`)

- **[Cursor](https://cursor.sh/)**: `.cursor/rules`, `.cursorrules` (`-a cursor`)

- **[Google Gemini](https://gemini.google.com/)**: `GEMINI.md`, `.gemini/styleguide.md` (`-a gemini`)

- **[Augment](https://augmentcode.com/)**: `.augment/rules`, `.augment/guidelines.md` (`-a augment`)

- **[Windsurf](https://codeium.com/windsurf)**: `.windsurf/rules`, `.windsurfrules` (`-a windsurf`)

- **[OpenCode.ai](https://opencode.ai/)**: `.opencode/agent`, `.opencode/command`, `.opencode/rules` (`-a opencode`)

- **[Codex](https://codex.ai/)**: `AGENTS.md`, `.codex/AGENTS.md` (`-a codex`)



### Additional Compatible Agents



- **Codeium**, **Tabnine**, **Amazon Q Developer** (CodeWhisperer)

- **Sourcegraph Cody**, **Continue**, **Aider**

- **Replit Ghostwriter**, **GitLab Duo**

- **All OpenAI models** (GPT-4, ChatGPT), **LLM APIs**

- **Agent frameworks**: LangChain, AutoGPT, BabyAGI

- **And 20+ more** - see [full documentation](https://kitproj.github.io/coding-context-cli/reference/supported-agents)



### Generic AI Agent Support



- **Generic AI Agents**: `AGENTS.md`, `.agents/rules`, `.agents/commands` (reusable content blocks), `.agents/tasks`



The tool automatically discovers and includes rules from these locations in your project and user home directory (`~`).



## Agentic Workflows



This tool plays a crucial role in the **agentic workflow ecosystem** by providing rich, contextual information to AI agents. It complements systems like **GitHub Next's Agentic Workflows** by:



- **Context Preparation**: Assembles rules, guidelines, and task-specific prompts before agent execution

- **Workflow Integration**: Can be invoked in GitHub Actions to provide context to autonomous agents

- **Dynamic Context**: Supports runtime parameters and bootstrap scripts for real-time information

- **Multi-Stage Support**: Different context assemblies for planning, implementation, and validation stages



For a comprehensive guide on using this tool with agentic workflows, see [AGENTIC_WORKFLOWS.md](./AGENTIC_WORKFLOWS.md).



## Installation



You can install the CLI by downloading the latest release from the [releases page](https://github.com/kitproj/coding-context-cli/releases) or by building from source.



### Linux



**AMD64:**

```bash

sudo curl -fsL -o /usr/local/bin/coding-context https://github.com/kitproj/coding-context-cli/releases/download/v0.0.34/coding-context_v0.0.34_linux_amd64

sudo chmod +x /usr/local/bin/coding-context

```



**ARM64:**

```bash

sudo curl -fsL -o /usr/local/bin/coding-context https://github.com/kitproj/coding-context-cli/releases/download/v0.0.34/coding-context_v0.0.34_linux_arm64

sudo chmod +x /usr/local/bin/coding-context

```



### MacOS



**Intel (AMD64):**

```bash

sudo curl -fsL -o /usr/local/bin/coding-context https://github.com/kitproj/coding-context-cli/releases/download/v0.0.34/coding-context_v0.0.34_darwin_amd64

sudo chmod +x /usr/local/bin/coding-context

```



**Apple Silicon (ARM64):**

```bash

sudo curl -fsL -o /usr/local/bin/coding-context https://github.com/kitproj/coding-context-cli/releases/download/v0.0.34/coding-context_v0.0.34_darwin_arm64

sudo chmod +x /usr/local/bin/coding-context

```



## Usage



```

Usage:

  coding-context [options]  [user-prompt]



Arguments:

  

      The name of a task file to look up in task search paths (.agents/tasks).

      Task files are matched by filename (without .md extension).

  

  [user-prompt] (optional)

      Optional text to append to the task. It can contain slash commands

      (e.g., '/command-name') which will be expanded, and parameter 

      substitution (${param}).



Options:

  -C string

    	Change to directory before doing anything. (default ".")

  -d value

    	Remote directory containing rules and tasks. Can be specified multiple times. Supports various protocols via go-getter (http://, https://, git::, s3::, etc.).

  -m string

    	Go Getter URL to a manifest file containing search paths (one per line). Every line is included as-is.

  -p value

    	Parameter to substitute in the prompt. Can be specified multiple times as key=value.

  -r	Resume mode: skip outputting rules and select task with 'resume: true' in frontmatter.

  -s value

    	Include rules with matching frontmatter. Can be specified multiple times as key=value.

    	Note: Only matches top-level YAML fields in frontmatter.

  -a string

    	Target agent to use. Required when using -w to write rules to the agent's user rules path. Supported agents: cursor, opencode, copilot, claude, gemini, augment, windsurf, codex.

  -w	Write rules to agent's config file and output only task to stdout. Requires agent (via task or -a flag).

```



### Examples



**Basic usage with local files:**

```bash

coding-context -p jira_issue_key=PROJ-1234 fix-bug | llm -m gemini-pro

```



This command will:

1. Find a task file named `fix-bug.md` in the task search paths.

2. Find all rule files in the search paths.

3. Filter the rules based on selectors.

4. Execute any associated bootstrap scripts.

5. Substitute `${jira_issue_key}` with `PROJ-1234` in the task prompt.

6. Print the combined context (rules + task) to `stdout`.

7. Pipe the output to another program (in this case, `llm`).



**Using remote directories:**

```bash

coding-context \

  -d git::https://github.com/company/shared-rules.git \

  -d s3::https://s3.amazonaws.com/my-bucket/coding-standards \

  fix-bug | llm -m gemini-pro

```



This command will:

1. Download remote directories using go-getter

2. Search for rules and tasks in the downloaded directories

3. Combine them with local rules and tasks

4. Apply the same processing as with local files



The `-d` flag supports various protocols via go-getter:

- `http://` and `https://` - HTTP/HTTPS URLs

- `git::` - Git repositories  

- `s3::` - S3 buckets

- `file://` - Local file paths

- And more (see go-getter documentation)



### Content Expansion Features



Task and rule content supports three types of dynamic expansion:



1. **Parameter Expansion**: Use `${parameter_name}` syntax to substitute parameter values from `-p` flags

   ```markdown

   Issue: ${issue_key}

   Description: ${description}

   ```



2. **Command Expansion**: Use `` !`command` `` syntax to execute shell commands and include their output

   ```markdown

   Current date: !`date +%Y-%m-%d`

   Git branch: !`git rev-parse --abbrev-ref HEAD`

   ```



3. **Path Expansion**: Use `@path` syntax to include file contents

   ```markdown

   Current configuration:

   @config.yaml

   ```



**Security Note:** All expansions are processed in a single pass to prevent injection attacks. Expanded content is never re-processed.



### Example Tasks



The `` corresponds to the filename (without the `.md` extension) of task files. Here are some common examples:



- `triage-bug`

- `review-pull-request`

- `fix-broken-build`

- `migrate-java-version`

- `enhance-docs`

- `remove-feature-flag`

- `speed-up-build`



Each of these would have a corresponding `.md` file (e.g., `triage-bug.md`, `fix-broken-build.md`).



## How It Works



The tool assembles the context in the following order:



1.  **Rule Files**: It searches for rule files (`.md` or `.mdc`) in directories specified via `-d` flags and automatically-added working directory and home directory.

2.  **Rule Bootstrap Scripts**: For each rule file found (e.g., `my-rule.md`), it looks for an executable script named `my-rule-bootstrap`. If found, it runs the script before processing the rule file. These scripts are meant for bootstrapping the environment (e.g., installing tools) and their output is sent to `stderr`, not into the main context.

3.  **Filtering**: If `-s` (include) flag is used, it parses the YAML frontmatter of each rule file to decide whether to include it. Note that selectors can only match top-level YAML fields (e.g., `language: go`), not nested fields.

4.  **Task Prompt**: It searches for a task file matching the filename (without `.md` extension). Tasks are matched by filename, not by `task_name` in frontmatter. If selectors are provided with `-s`, they are used to filter between multiple task files with the same filename.

5.  **Task Bootstrap Script**: For the task file found (e.g., `fix-bug.md`), it looks for an executable script named `fix-bug-bootstrap`. If found, it runs the script before processing the task file. This allows task-specific environment setup or data preparation.

6.  **User Prompt Appending**: If a user-prompt argument is provided, it is appended to the task content after a delimiter (`---`).

7.  **Parameter Expansion**: It substitutes variables in the task prompt and user-prompt using the `-p` flags.

8.  **Output**: It prints the content of all included rule files, followed by the expanded task prompt, to standard output.

9.  **Token Count**: A running total of estimated tokens is printed to standard error.



### File Search Paths



The tool automatically searches for task and rule files in various locations. For a complete reference, see the [Search Paths documentation](https://kitproj.github.io/coding-context-cli/reference/search-paths).



**Common locations:**

- `./.agents/tasks/*.md` - Task definitions

- `./.agents/rules/` - Rule files  

- `./.agents/commands/` - Reusable command blocks

- `./.agents/skills/*/SKILL.md` - Specialized skills

- Various agent-specific paths (`.cursor/`, `.github/`, `.opencode/`, etc.)

- User-wide rules in `~/.agents/rules`, `~/.claude/`, `~/.codex/`, etc.



See the full [Search Paths Reference](https://kitproj.github.io/coding-context-cli/reference/search-paths) for the complete list of locations.



### Remote File System Support



The tool supports loading rules and tasks from remote locations via HTTP/HTTPS URLs. This enables:



- **Shared team guidelines**: Host coding standards on a central server

- **Organization-wide rules**: Distribute common rules across multiple projects

- **Version-controlled context**: Serve rules from Git repositories

- **Dynamic rules**: Update shared rules without modifying individual repositories



**Usage:**



```bash

# Clone a Git repository containing rules

coding-context -d git::https://github.com/company/shared-rules.git /fix-bug



# Use multiple remote sources

coding-context \

  -d git::https://github.com/company/shared-rules.git \

  -d https://cdn.company.com/coding-standards \

  /deploy



# Mix local and remote directories

coding-context \

  -d git::https://github.com/company/shared-rules.git \

  -s languages=go \

  /implement-feature

```



**Supported protocols (via go-getter):**

- `http://` and `https://` - HTTP/HTTPS URLs (downloads tar.gz, zip, or directories)

- `git::` - Git repositories (e.g., `git::https://github.com/user/repo.git`)

- `s3::` - S3 buckets (e.g., `s3::https://s3.amazonaws.com/bucket/path`)

- `file://` - Local file paths

- And more - see [go-getter documentation](https://github.com/hashicorp/go-getter)



**Important notes:**

- Remote directories are downloaded to a temporary location

- Bootstrap scripts work in downloaded directories

- Downloaded directories are cleaned up after execution

- Supports all standard directory structures (`.agents/rules`, `.agents/tasks`, etc.)



**Example: Using a Git repository:**



```bash

# Use a specific branch or tag

coding-context \

  -d 'git::https://github.com/company/shared-rules.git?ref=v1.0' \

  /fix-bug



# Use a subdirectory within the repo

coding-context \

  -d 'git::https://github.com/company/mono-repo.git//coding-standards' \

  /implement-feature

```



## File Formats



### Task Files



Task files are Markdown files located in task search directories (e.g., `.agents/tasks/`). Tasks are matched by filename (without the `.md` extension), not by frontmatter fields. The `task_name` field in frontmatter is optional metadata. Task files can contain variables for substitution and can use selectors in frontmatter to filter between multiple task files with the same filename in different locations.



**Example (`.agents/tasks/fix-bug.md`):**

```markdown

# Task: Fix Bug in ${jira_issue_key}



Here is the context for the bug. Please analyze the following files and provide a fix.

```



**Example with selectors for multiple prompts (`.agents/tasks/deploy-staging.md`):**

```markdown

---

environment: staging

---

# Deploy to Staging



Deploy the application to the staging environment with extra validation.

```



**Example for production (`.agents/tasks/deploy-prod.md`):**

```markdown

---

environment: production

---

# Deploy to Production



Deploy the application to production with all safety checks.

```



You can then select the appropriate task using:

```bash

# Deploy to staging

coding-context -s environment=staging deploy



# Deploy to production

coding-context -s environment=production deploy

```



#### Task Frontmatter Selectors



Task files can include a `selectors` field in their frontmatter to automatically filter rules without requiring explicit `-s` flags on the command line. This is useful for tasks that always need specific rules.



**Example (`.agents/tasks/implement-go-feature.md`):**

```markdown

---

selectors:

  languages: go

  stage: implementation

---

# Implement Feature



Implement the feature following Go best practices and implementation guidelines.

```



When you run this task, it automatically applies the selectors:

```bash

# This command automatically includes only rules with languages=go and stage=implementation

coding-context implement-feature

```



**Selectors support OR logic for the same key using arrays:**

```markdown

---

selectors:

  languages: [go, python]

  stage: testing

---

```



This will include rules that match `(languages=go OR languages=python) AND stage=testing`.



**Combining task selectors with command-line selectors:**



Selectors from both the task frontmatter and command line are combined (additive):

```bash

# Task has: selectors.languages = go

# Command adds: -s priority=high

# Result: includes rules matching languages=go AND priority=high

coding-context -s priority=high implement-feature

```



### Parameter Expansion Control



By default, parameter expansion occurs in all task and rule content. You can disable this behavior using the `expand` frontmatter field.



**Example (task with expansion disabled):**

```yaml

---

expand: false

---



Issue: ${issue_number}

Title: ${issue_title}

```



When `expand: false` is set, parameter placeholders like `${variable}` are preserved as-is in the output, rather than being replaced with values from `-p` flags.



**Use cases:**

- Passing templates to AI agents that handle their own parameter substitution

- Preserving template syntax for later processing

- Avoiding conflicts with other templating systems



The `expand` field works in:

- Task files (`.agents/tasks/*.md`)

- Command files (`.agents/commands/*.md`)

- Rule files (`.agents/rules/*.md`)



### Resume Mode



Resume mode is designed for continuing work on a task where you've already established context. When using the `-r` flag:



1. **Rules are skipped**: All rule files are excluded from output, saving tokens and reducing context size

2. **Resume-specific task prompts are selected**: Automatically adds `-s resume=true` selector to find task files with `resume: true` in their frontmatter



This is particularly useful in agentic workflows where an AI agent has already been primed with rules and is continuing work from a previous session.



**The `-r` flag is shorthand for:**

- Adding `-s resume=true` selector

- Skipping all rules output



**Example usage:**

```bash

# Initial task invocation (includes all rules, uses task with resume: false)

coding-context -s resume=false fix-bug | ai-agent



# Resume the task (skips rules, uses task with resume: true)

coding-context -r fix-bug | ai-agent

```



**Example task files for resume mode:**



Initial task (`.agents/tasks/fix-bug-initial.md`):

```markdown

---

resume: false

---

# Fix Bug



Analyze the issue and implement a fix.

Follow the coding standards and write tests.

```



Resume task (`.agents/tasks/fix-bug-resume.md`):

```markdown

---

resume: true

---

# Fix Bug - Continue



Continue working on the bug fix.

Review your previous work and complete remaining tasks.

```



With this approach, you can have multiple task prompts for the same task name, differentiated by the `resume` frontmatter field. Use `-s resume=false` to select the initial task (with rules), or `-r` to select the resume task (without rules).



### Rule Files



Rule files are Markdown (`.md`) or `.mdc` files, optionally with YAML frontmatter for filtering.



**Example (`.agents/rules/backend.md`):**

```markdown

---

languages:

  - go

---



# Backend Coding Standards



- All new code must be accompanied by unit tests.

- Use the standard logging library.

```



To include this rule only when working on Go code, you would use `-s languages=go`:



```bash

coding-context -s languages=go fix-bug

```



This will include all rules with `languages: [ go ]` in their frontmatter, excluding rules for other languages.



**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`). The frontmatter field is `languages` (plural) with array format.



**Example: Language-Specific Rules**



You can create multiple language-specific rule files:



- `.agents/rules/python-standards.md` with `languages: [ python ]`

- `.agents/rules/javascript-standards.md` with `languages: [ javascript ]`

- `.agents/rules/go-standards.md` with `languages: [ go ]`



Then select only the relevant rules:



```bash

# Work on Python code with Python-specific rules

coding-context -s languages=python fix-bug



# Work on JavaScript code with JavaScript-specific rules

coding-context -s languages=javascript enhance-feature

```



**Language Values**



When using language selectors, language values should be **lowercase** (e.g., `go`, `python`, `javascript`, `java`, `typescript`). The frontmatter field should be `languages` (plural) in array format:



```yaml

---

languages:

  - go

  - python

---

```



**Common languages (lowercase):**

- `c`, `csharp` (C#), `cpp` (C++), `css`

- `dart`, `elixir`, `go`, `haskell`, `html`

- `java`, `javascript`, `kotlin`, `lua`, `markdown`

- `objectivec` (Objective-C), `php`, `python`, `ruby`, `rust`

- `scala`, `shell`, `swift`, `typescript`, `yaml`



**Note:** Language values should be lowercase in frontmatter and selectors.



**Note:** Frontmatter selectors can only match top-level YAML fields. For example:

- ✅ Works: `languages: [ go ]` matches `-s languages=go`

- ❌ Doesn't work: Nested fields like `metadata.version: 1.0` cannot be matched with `-s metadata.version=1.0`



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:



1. **Write Rules Mode**: With the `-w` flag, determines where to write rules (e.g., `~/.github/agents/AGENTS.md` for `copilot`)



> **Note:** Agent-based rule filtering is not currently implemented. All rules are included regardless of the `-a` value.



**Supported agents:**

- `cursor` - Cursor IDE

- `opencode` - OpenCode.ai  

- `copilot` - GitHub Copilot

- `claude` - Anthropic Claude

- `gemini` - Google Gemini

- `augment` - Augment

- `windsurf` - Windsurf

- `codex` - Codex



**Example:**



```bash

# Use with write rules mode

coding-context -a copilot -w fix-bug

```



**How it works:**

- The `-a` flag sets the target agent value

- The agent value is stored in the context for use by the `-w` flag

- With `-w`, the agent determines where to write rules to the user's home directory

- All rules are currently included regardless of agent value



**Agent field in task frontmatter:**



Tasks can specify an `agent` field in their frontmatter, which overrides the `-a` command-line flag:



```markdown

---

agent: cursor

---

# This task automatically sets the agent to cursor

```



This is useful for tasks designed for specific agents, ensuring the correct agent is set for determining the write path with `-w`.



### Bootstrap Scripts



A bootstrap script is an executable file that has the same name as a rule or task file but with a `-bootstrap` suffix. These scripts are used to prepare the environment, for example by installing necessary tools. The output of these scripts is sent to `stderr` and is not part of the AI context.



**Examples:**

- Rule file: `.agents/rules/jira.md`

- Rule bootstrap script: `.agents/rules/jira-bootstrap`

- Task file: `.agents/tasks/fix-bug.md`

- Task bootstrap script: `.agents/tasks/fix-bug-bootstrap`



Bootstrap scripts are executed in the following order:

1. Rule bootstrap scripts run before their corresponding rule files are processed

2. Task bootstrap scripts run after all rules are processed but before the task content is emitted



**`.agents/rules/jira-bootstrap`:**

```bash

#!/bin/bash

# This script installs the jira-cli if it's not already present.

if ! command -v jira-cli &> /dev/null

then

    echo "Installing jira-cli..." >&2

    # Add installation commands here

fi

```



**`.agents/tasks/fix-bug-bootstrap`:**

```bash

#!/bin/bash

# This script fetches the latest issue details before the task runs.

echo "Fetching issue information..." >&2

# Fetch and prepare issue data

```



### Command Files (Slash Commands)



Command files are reusable content blocks that can be referenced from task files using slash command syntax (e.g., `/command-name`). They enable modular, composable task definitions.



**Example command file (`.agents/commands/pre-deploy.md`):**

```markdown

---

expand: true

---

# Pre-deployment Checklist



Run tests: !`npm test`

Build status: !`git status`

```



**Using commands in a task (`.agents/tasks/deploy.md`):**

```markdown

# Deployment Task



/pre-deploy



Deploy the application to ${environment}.



/post-deploy

```



Commands can also receive inline parameters:

```markdown

/greet name="Alice"

/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 contains metadata used for filtering, agent selection, and workflow automation. While the frontmatter itself is not included in the generated output, it serves important purposes:



**What frontmatter is used for:**

- **Task selection**: Filtering between multiple task files using selectors

- **Agent specification**: The `agent` field can override the `-a` command-line flag

- **Rule filtering**: The `selectors` field automatically filters rules without requiring explicit `-s` flags

- **Workflow control**: Fields like `resume` control task behavior in different modes



**Example usage:**

```bash

coding-context -p issue_number=123 fix-bug

```



**Example task file:**

```markdown

---

resume: false

selectors:

  languages: go

  stage: implementation

---

# Fix Bug Task



Fix the bug in issue #${issue_number}...

```



**Output format:**

The task frontmatter is NOT included in the output. Only the task content (below the frontmatter delimiters) is included:

```markdown

# Fix Bug Task



Fix the bug in issue #123...

```



This design keeps the output focused on actionable content while still allowing frontmatter to control behavior and filtering.



**Example with selectors in frontmatter:**

```bash

coding-context implement-feature

```



If the task has `selectors` in its frontmatter, they will automatically filter rules, but the frontmatter itself won't appear in the output:

```markdown

# Implementation Task

...

```



## Presentations



A comprehensive slide deck is available for presenting and learning about the Coding Context CLI:



- **[View Slide Deck](./SLIDES.md)** - Full presentation with 50+ slides

- **[Presentation Guide](./SLIDES_README.md)** - How to view, export, and present

- **[Example Usage](./examples/PRESENTATION.md)** - Presentation scenarios and tips



The slides are written in [Marp](https://marp.app/) format and can be:

- Viewed in VS Code with the Marp extension

- Exported to HTML, PDF, or PowerPoint

- Presented directly from a browser

- Customized for your audience



Perfect for:

- **Team onboarding** - Introduce the tool to new team members

- **Tech talks** - Present at meetups or conferences

- **Workshops** - Run hands-on training sessions

- **Documentation** - Visual reference for features



## Troubleshooting



### Common Issues



**Task not found**

- Verify the task file exists in `.agents/tasks/` with the correct filename

- Tasks are matched by filename (without `.md` extension), not by `task_name` in frontmatter

- Check that you're using the correct task name: `coding-context fix-bug` (not `/fix-bug`)



**No rules included**

- Check that rule files exist in search paths (`.agents/rules/`, etc.)

- Verify selector syntax: use `-s languages=go` (not `-p languages=go`)

- Remember: `-s` filters rules, `-p` substitutes parameters

- Rules without frontmatter are always included (unless using resume mode)



**Parameters not substituted**

- Ensure you're using `-p` flag: `coding-context -p issue=123 fix-bug`

- Check parameter names match exactly (case-sensitive): `${issue_key}` matches `-p issue_key=...`

- Verify the task file uses `${parameter}` syntax



**Wrong rules included**

- Check frontmatter spelling and case sensitivity

- Use `languages:` (plural) in frontmatter and `-s languages=go` in selectors

- All selectors must match (AND logic): `-s languages=go -s stage=testing`



**Bootstrap script not running**

- Make the script executable: `chmod +x .agents/rules/my-rule-bootstrap`

- Name it correctly: `{rule-filename}-bootstrap` (e.g., `jira-context-bootstrap` for `jira-context.md`)

- Check script output in stderr



For more help, see the [full documentation](https://kitproj.github.io/coding-context-cli/) or [open an issue](https://github.com/kitproj/coding-context-cli/issues).