Skip to content

Document skills in "How It Works" section #190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Copilot wants to merge 3 commits into from
Closed

Document skills in "How It Works" section #190

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c1aa4ec
Initial plan
Copilot Dec 25, 2025
306c2dd
Document skills in README "How It Works" section
Copilot Dec 25, 2025
636cb19
Fix additional README errors - mention skills in examples
Copilot Dec 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 17 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ 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.).
Remote directory containing rules, skills, 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
Expand All @@ -137,10 +137,11 @@ 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`).
4. Discover available skills and load their metadata.
5. Execute any associated bootstrap scripts.
6. Substitute `${jira_issue_key}` with `PROJ-1234` in the task prompt.
7. Print the combined context (rules + skills + task) to `stdout`.
8. Pipe the output to another program (in this case, `llm`).

**Using remote directories:**
```bash
Expand All @@ -152,8 +153,8 @@ coding-context \

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
2. Search for rules, skills, and tasks in the downloaded directories
3. Combine them with local rules, skills, and tasks
4. Apply the same processing as with local files

The `-d` flag supports various protocols via go-getter:
Expand Down Expand Up @@ -208,12 +209,13 @@ 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.
4. **Skill Discovery**: It searches for skill directories (`.agents/skills/*/SKILL.md`) and loads only their metadata (name and description) for progressive disclosure. Skills can be filtered by selectors just like rules.
5. **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.
6. **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.
7. **User Prompt Appending**: If a user-prompt argument is provided, it is appended to the task content after a delimiter (`---`).
8. **Parameter Expansion**: It substitutes variables in the task prompt and user-prompt using the `-p` flags.
9. **Output**: It prints the content of all included rule files, followed by available skills metadata (as XML for progressive disclosure), followed by the expanded task prompt, to standard output.
Copy link

Copilot AI Dec 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This description of the output order is incomplete and may mislead users. Based on the code in main.go (lines 160-181) and pkg/codingcontext/context.go (lines 345-367), the actual output order is:

  1. Task frontmatter (if present)
  2. Skills XML
  3. Rules content
  4. Skills section (with "# Skills" heading and XML again)
  5. Task content

The current description says "rules, followed by skills, followed by task" which:

  • Omits that task frontmatter appears first
  • Incorrectly suggests rules come before skills (skills XML actually appears after frontmatter but before rules)
  • Doesn't mention that skills metadata appears twice in the output (once standalone after task frontmatter, and again between rules and task content)

Consider revising to: "It prints the task frontmatter (if present), followed by available skills metadata (as XML), then the combined prompt (containing all included rule files, skills section, and the expanded task content), to standard output."

Note: The duplication of skills in the output may be unintentional (see main.go lines 169-178 and context.go lines 352-364).

Suggested change
9. **Output**: It prints the content of all included rule files, followed by available skills metadata (as XML for progressive disclosure), followed by the expanded task prompt, to standard output.
9. **Output**: It prints the task frontmatter (if present), followed by available skills metadata (as XML), then the combined prompt (containing all included rule files, skills section, and the expanded task content), to standard output.

Copilot uses AI. Check for mistakes.
10. **Token Count**: A running total of estimated tokens is printed to standard error.

### File Search Paths

Expand All @@ -240,7 +242,7 @@ The tool searches for a variety of files and directories, including:

### Remote File System Support

The tool supports loading rules and tasks from remote locations via HTTP/HTTPS URLs. This enables:
The tool supports loading rules, skills, 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
Expand Down Expand Up @@ -277,7 +279,7 @@ coding-context \
- 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.)
- Supports all standard directory structures (`.agents/rules`, `.agents/skills`, `.agents/tasks`, etc.)

**Example: Using a Git repository:**

Expand Down