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.
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
- Verify claims against the repository, tool, or documented behavior; remove generic placeholders and aspirational rules.
- Apply the precision and compression rules to prose, instructions, and examples.
- Remove repeated conclusions, obvious callouts, and history that does not affect execution.
Reference Files
| File | Load When |
|---|---|
| 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: 467k | 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: 319k | 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: 319k | 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: 319k | Updated | Claude CodeCodex | Verified | Install |