feat(ai): agent skill #1707
feat(ai): agent skill #1707
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
ecosystem/ai/agent-skill.mdx
Outdated
|
|
||
| Agent Skills are an open format for packaging instructions, scripts, and resources that skills-compatible agents can discover and apply. | ||
|
|
||
| See https://agentskills.io/home for an overview and links to the specification. |
There was a problem hiding this comment.
[HIGH] Bare URL used as link text in prose
Line 13 uses a bare URL in prose (See https://agentskills.io/home for an overview…) instead of descriptive link text. This violates the style rule requiring meaningful link labels, which improves accessibility, readability, and clarity when links are read out of context or via assistive technologies. A descriptive label also makes it clearer what the destination represents (the Agent Skills overview) without forcing the reader to parse the raw URL.
| See https://agentskills.io/home for an overview and links to the specification. | |
| See the [Agent Skills overview](https://agentskills.io/home) for an overview and links to the specification. |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
|
|
||
| ## Prerequisites | ||
|
|
||
| - The agent you use supports “Skills” (a `SKILL.md` file with frontmatter) |
There was a problem hiding this comment.
[HIGH] Reader-directed pronoun and decorative quotes in prerequisites
The prerequisite bullet on line 17 uses the phrase “The agent you use”, which addresses the reader directly in the second person. The same line also wraps the term “Skills” in quotation marks used for emphasis rather than as a literal UI string. The style guide’s “Don’t get personal” and quotation-mark rules require neutral phrasing without “you/your” and discourage decorative quotes for emphasized terminology. Rewriting this bullet to use third-person, neutral language and plain capitalization for Skills keeps the meaning while conforming to the house style.
| - The agent you use supports “Skills” (a `SKILL.md` file with frontmatter) |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
|
|
||
| ## Install in Codex | ||
|
|
||
| Run this in Codex: |
There was a problem hiding this comment.
[HIGH] Reader-directed phrasing in Codex instructions
Line 21 reads “Run this in Codex:”, which implicitly addresses the reader and uses conversational phrasing. The style guide for documentation favors neutral, imperative instructions that describe what to do without talking to “you” as a person. Rephrasing this line to refer to the command itself rather than the reader keeps the step clear while aligning with the required tone.
| Run this in Codex: | |
| Run the following command in Codex: |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ``` | ||
| $skill-installer --url https://github.com/ton-org/docs/tree/main/skills/ton-blockchain | ||
| ``` |
There was a problem hiding this comment.
[HIGH] Shell prompt token and missing language tag in skill-installer command
The fenced block on lines 23–25 shows the command as $skill-installer ... inside an untyped code fence. Including a $-style prompt in command examples conflicts with the guideline that examples must be copy-pasteable without editing out prompts. The same block also omits a language identifier, whereas other command examples in the file consistently use bash, and the style guide requires specifying a language for all fenced code blocks. Updating this block to remove the prompt token and to label the fence with bash addresses both issues and keeps command examples consistent.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
|
|
||
| ## Install in Claude Code | ||
|
|
||
| This installs it as a personal Skill: |
There was a problem hiding this comment.
[HIGH] Reader-directed phrasing in Claude Code instructions
The sentence on line 31, “This installs it as a personal Skill:”, uses conversational, reader-targeted phrasing rather than a neutral imperative. The documentation style guide prefers direct instructions that describe the action to take, without framing the text as a commentary for the reader. Rewriting this line into an imperative instruction keeps the meaning and aligns with the neutral, fact-focused tone.
| This installs it as a personal Skill: | |
| Install this as a personal Skill: |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
skills/ton-blockchain/SKILL.md
Outdated
| @@ -0,0 +1,58 @@ | |||
| --- | |||
| name: ton-blockchain | |||
| description: "Use when working with The Open Network (TON) blockchain, or when the user mentions TON-ecosystem terms the agent may not recognize—such as Tact, FunC, Tolk, Fift, TL-B, TVM, cells, BOC, Jettons, TEPs, TON Connect, workchains, shardchains, or liteservers. Provides a docs-first workflow for fetching and navigating TON documentation accurately, and covers smart contract development, transaction mechanics, wallet standards, token standards, Telegram Mini Apps, and infrastructure." | |||
There was a problem hiding this comment.
[HIGH] Conversational and marketing-style SKILL description
The description field on line 3 combines conversational role language (“when the user mentions … the agent may not recognize”) with promotional phrasing (“Provides a docs-first workflow … accurately”), which reads as marketing-style copy. The style guide calls for neutral, factual descriptions without referring to conversational roles like “user” within documentation text, and it discourages value-laden claims about accuracy or workflows. A more concise, capability-focused description that simply states what the skill covers and that TON Docs is the primary reference will better match the required tone.
| description: "Use when working with The Open Network (TON) blockchain, or when the user mentions TON-ecosystem terms the agent may not recognize—such as Tact, FunC, Tolk, Fift, TL-B, TVM, cells, BOC, Jettons, TEPs, TON Connect, workchains, shardchains, or liteservers. Provides a docs-first workflow for fetching and navigating TON documentation accurately, and covers smart contract development, transaction mechanics, wallet standards, token standards, Telegram Mini Apps, and infrastructure." | |
| description: "Use for tasks involving The Open Network (TON) blockchain and TON-ecosystem concepts such as Tact, FunC, Tolk, Fift, TL-B, TVM, cells, BOC, jettons, TEPs, TON Connect, workchains, shardchains, and liteservers. Covers smart contract development, transaction mechanics, wallet and token standards, Telegram Mini Apps, and TON infrastructure, using TON Docs as the primary reference." |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ```bash | ||
| curl -fsSL https://docs.ton.org/llms.txt | rg -n "<topic>|<keyword>" || true | ||
| ``` | ||
|
|
||
| (Use `grep -nE` instead of `rg` if ripgrep isn’t available.) | ||
|
|
||
| ## 3) Pull only the pages you need | ||
|
|
||
| For any relevant page path from `llms.txt`, prefer the Markdown source by appending `.md`: | ||
|
|
||
| ```bash | ||
| curl -fsSL "https://docs.ton.org/<page-path>.md" | ||
| ``` | ||
|
|
||
| If that 404s, try the path as-is (some entries may already include `.md` or may not support source rendering): | ||
|
|
||
| ```bash | ||
| curl -fsSL "https://docs.ton.org/<page-path>" |
There was a problem hiding this comment.
[HIGH] Undocumented <ANGLE_CASE> placeholders in commands
The workflow introduces <topic>, <keyword>, and <page-path> placeholders directly inside runnable curl and rg commands (for example in the search pattern on line 35 and in the page fetch commands on lines 45 and 51) without defining what values should be substituted. The style guide requires that angle-bracketed placeholders in commands be explicitly defined on first use so examples remain copy-pasteable and unambiguous. Without short definitions, users and tools may misinterpret these parameters or be unsure how to construct valid queries and paths.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
closes #1706