Skip to content

Clear and concise grammar tends to perform better with agents #221

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

Open
OndrejHana wants to merge 1 commit into
base: main
Choose a base branch
from
+19 −21
Open

Clear and concise grammar tends to perform better with agents #221

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
40 changes: 19 additions & 21 deletions skills/btca-local/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,55 +5,51 @@ description: Invoke this skill when the user says "use btca"

# BTCA Local

BTCA Local, aka "The Better Context App Local" is a simple app defined as a skill file. The purpose of this app is to search git repos cloned onto this machine.
BTCA Local, aka "The Better Context App Local" is a simple app defined as a skill file. It's purpose is to improve the agent's capabilities for answering questions based on git repositories, cloned on this machine.
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot Apr 12, 2026

Choose a reason for hiding this comment

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

P2 "It's" should be "Its"

It's is a contraction for "it is"; the possessive form Its is needed here.

Suggested change
BTCA Local, aka "The Better Context App Local" is a simple app defined as a skill file. It's purpose is to improve the agent's capabilities for answering questions based on git repositories, cloned on this machine.
BTCA Local, aka "The Better Context App Local" is a simple app defined as a skill file. Its purpose is to improve the agent's capabilities for answering questions based on git repositories, cloned on this machine.
Prompt To Fix With AI 
This is a comment left during a code review.
Path: skills/btca-local/SKILL.md
Line: 8

Comment:
**"It's" should be "Its"**

`It's` is a contraction for "it is"; the possessive form `Its` is needed here.

```suggestion
BTCA Local, aka "The Better Context App Local" is a simple app defined as a skill file. Its purpose is to improve the agent's capabilities for answering questions based on git repositories, cloned on this machine. 
```

How can I resolve this? If you propose a fix, please make it concise.


## the BTCA Search Workflow

<guidelines>
<guideline>
if the user includes a direct like to a github repo, always load and reference that
If the user includes a direct like to a github repo, always load and reference that.
</guideline>
<guideline>
if the user doesn't include any specific links/repos they want you to use, do your best to guess based on the context provided
If the user doesn't include any specific links/repos, do your best to guess based on the provided context.
</guideline>
<guideline>
always include links/citations in your answers explaining what you found
Always include links and citations in your answers explaining what you found.
</guideline>
<guideline>
include very clear and complete code snippets. don't leave out stuff like imports, that's important context
Include very clear and complete code snippets. Don't leave out imports and error handling, that's an important context.
</guideline>
<guideline>
when answering use lots of bulleted/numbered lists to keep things readable and clear
Be extremly concise in all interactions. Sacrifice grammer for the sake of concision.
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot Apr 12, 2026

Choose a reason for hiding this comment

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

P1 Guideline replaced + typos in new text

This replaces the original instruction to "use lots of bulleted/numbered lists to keep things readable and clear" with advice to "Sacrifice grammer for the sake of concision" — which removes structured-output behavior entirely and introduces two typos (extremly, grammer). Agent instructions like this directly shape output quality, so dropping the list/readability guideline is a functional regression, and the misspellings undermine the PR's stated goal of improving grammar clarity.

Suggested change
Be extremly concise in all interactions. Sacrifice grammer for the sake of concision.
Be extremely concise in all interactions. Use bulleted or numbered lists to keep answers readable and clear.
Prompt To Fix With AI 
This is a comment left during a code review.
Path: skills/btca-local/SKILL.md
Line: 26

Comment:
**Guideline replaced + typos in new text**

This replaces the original instruction to "use lots of bulleted/numbered lists to keep things readable and clear" with advice to "Sacrifice grammer for the sake of concision" — which removes structured-output behavior entirely and introduces two typos (`extremly`, `grammer`). Agent instructions like this directly shape output quality, so dropping the list/readability guideline is a functional regression, and the misspellings undermine the PR's stated goal of improving grammar clarity.

```suggestion
        Be extremely concise in all interactions. Use bulleted or numbered lists to keep answers readable and clear.
```

How can I resolve this? If you propose a fix, please make it concise.

</guideline>
</guidelines>

<workflow>
<step name="work dir setup">
use ~/.btca/agent/sandbox as the place where you clone/search repos
Store your cloned repositories into `~/.btca/agent/sandbox`.
</step>
<step name="load">
if the repo(s) are already in the work dir ~/.btca/agent/sandbox update them, otherwise clone them. clone the main branch by default, unless the user asks for something else
If the repository is already inside your working directory `~/.btca/agent/sandbox`, update it, otherwise clone it. Clone the main branch, unless the user specifies otherwise.
</step>
<step name="search">
search the repo for the information you need. make sure to follow the guidelines
Search the repository for the required information. Make sure you follow the guidelines.
</step>
<workflow>

<end_goal>
a clear, concise answer to the question with code examples
A clear and concise answer to the question with code examples.
</end_goal>

## Startup Cases:

This skill can be invoked in a couple different ways, and your behavior should reflect that:
This skill can be invoked in the following ways. Make sure your behaviour reflects that.

### user invoked without extra context/question
### User invoked you without a question

this is the "app startup" state, almost as if a terminal app was booted up.

Your job is to search the working directory ~/.btca/agent/sandbox at the top level, just to get a list of all the repos that have been previously cloned

Then you should simply output the following markdown (filling in the existing repos):
Start by searching inside the top level of your working directory `~/.btca/agent/sandbox` to get a list of all previously cloned repositories. Then output the following markdown:

```md
# BTCA Local
Expand All @@ -69,10 +65,12 @@ Give me a question and the link to a git repo to get started!
(we can also clean out or pre-load some resources to this list...)
```

### you invoked because of user's prompt
This is an "app startup" state, similar to being launched inside as a terminal application.

### You have been invoked because of the user's prompt

in this case, your job is to answer/execute the users prompt faithfully, just while also using the btca search workflow when needed to better execute your task
Answer and execute the user's prompt. Use the BTCA search workflow to improve your understanding of the users context.

### user invoked while also giving a prompt/questions
### User manually invoked you while providing a question or prompt

this one's simple, simply answer the users prompt with the btca search workflow
Answer the prompt using the BTCA search workflow.