Add README.md to .agents/skills/ explaining the skills system? | Voters

Add README.md to .agents/skills/ explaining the skills system?

serhat dolmaci

Hi team! 👋

I noticed that

.agents/skills/

contains 12 well-structured SKILL.md files

but has no README or index document at either

.agents/

.agents/skills/

level.

As Blockscout's AI-assisted development tooling grows, a brief README could help:

agents (Claude Code / Cursor / etc.), and the conventions used

when to create a skill vs. expand an existing one)

Would a PR adding such a README be welcome? If yes, I'd be happy to draft one.

If the current setup is intentional (e.g., the frontmatter of each SKILL.md

is designed to be self-sufficient), that's useful context too.

Thanks for building this the skill format is really clean!

Alex Kolotov

Hey! Thanks for your interest of development with Blockscout!

Here is my view on the comments your raised:

The frontmatter of each skill is designed (per the SKILLS standard) to be self-sufficient. The agents take the frontmatter of each skill and append it to the agent’s system prompt to assist an LLM in the selection of a corresponding skill. An index in the README.md file could be useful for human beings but will require an extra step for this index to be up-to-date when a new skill is created or its definition is updated. I would suggest an opposite approach if you would like to understand what skills are. Ask your agent “Inspect .agents/skills directory and provide a concise description for each of them with clarification in which scenarios they can be used during the Blockscout development process.” By doing so, you will always receive actual information about the skill, in your local language, with the level of explanation most comfortable for you.
No need to write a guideline for the skill preparation. Claude Code, Codex, and others already provide the skill like “Skill Creator”. Use it to create the best skill name, description, and body. The same approach you can use to decide whether a new skill or the existing skill adjustment is required — ask the agent “Use Skill Creator to inspect .agents/skills to decide whether the new skill or adjustment of the skill is required to solve/implement the behavior <put your problem here>.”