NetFabric/intelligentium / .agents/skills/agent-markdown-best-practices
agent-markdown-best-practices
VerifiedALWAYS use when writing or reviewing agent-facing Markdown, including project instructions, skills and references, and custom-agent definitions. Covers only their shared content style: compact executable instructions, scannable information, active language, factual precision, and token efficiency. DO NOT USE FOR: artifact-specific structure, routing descriptions, metadata schemas, or prompt-body requirements; general Markdown documents; Markdown syntax or rendering rules.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.3 KB |
| references/compact-agent-content.md | markdown | 1.5 KB |
SKILL.md
View on GitHub---
name: agent-markdown-best-practices
description: "ALWAYS use when writing or reviewing agent-facing Markdown, including project instructions, skills and references, and custom-agent definitions. Covers only their shared content style: compact executable instructions, scannable information, active language, factual precision, and token efficiency. DO NOT USE FOR: artifact-specific structure, routing descriptions, metadata schemas, or prompt-body requirements; general Markdown documents; Markdown syntax or rendering rules."
---
# Agent Markdown Best Practices
Agent-facing Markdown is operational context. Keep explanation when it changes interpretation or behavior; remove words that do not.
## Core Rules
| Rule | Do | Don't |
| --- | --- | --- |
| Executable over descriptive | "Run `pnpm test`" | "Make sure tests pass" |
| Concrete over aspirational | Record verified commands and enforced conventions | Describe practices the project does not follow |
| Active and imperative | "Inspect the diff" | "The diff should be inspected" |
| No preamble | Start with the role, rule, or first useful section | "This file describes..." |
| No restatement | Let headings, structured fields, and code express what they already say | Repeat metadata or section titles in prose |
| Structured over discursive | Use a table, short list, or numbered protocol for scannable facts | Hide operational facts in long paragraphs |
| Avoid duplicate sources | Keep required instructions local; link supporting detail that remains available at use time | Copy nonessential background or policy prose into agent context |
| One purpose per section | Split unrelated concerns under clear headings | Mix independent rules in one block |
Compactness never removes a command, flag, constraint, caveat, or prerequisite that changes behavior. Cut words, not facts.
## Workflow
1. Verify claims against the repository, tool, or documented behavior; remove generic placeholders and aspirational rules.
2. Apply the precision and compression rules to prose, instructions, and examples.
3. Remove repeated conclusions, obvious callouts, and history that does not affect execution.
## Reference Files
| File | Load When |
| --- | --- |
| [references/compact-agent-content.md](references/compact-agent-content.md) | Structuring or tightening any agent-facing Markdown |Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |