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 |
references/compact-agent-content.md
View on GitHub# Compact Agent Content
## Content Decisions
| Need | Best Form |
| --- | --- |
| Ordered actions | Numbered workflow with concrete verbs |
| Commands or comparable facts | Table or compact bullet list |
Use prose when sequence, rationale, or nuance would be distorted by a table. Tables are a compression tool, not a default decoration.
## Precision Rules
| Concern | Rule |
| --- | --- |
| Obligation | Use `must` for requirements, `should` for recommendations, and `may` for options |
| Completeness | State the action and target; add the condition or expected result when it affects execution or completion |
| Scope | Identify which files, tasks, tools, or circumstances a rule governs |
| Exceptions | Place an exception beside the rule it modifies |
| Precedence | State which instruction wins when rules can conflict |
| Terminology | Use one consistent term for each concept |
| Criteria | Replace subjective terms such as "properly" or "as needed" with observable conditions |
| Specificity | Replace ambiguous pronouns with the command, file, tool, or result they name |
| Prohibitions | Name the required alternative or fallback when one exists |
## Compression Decisions
- Keep rationale only when it changes how an instruction should be applied.
- Keep examples only when they disambiguate syntax or behavior.
- Convert generic callouts such as "Note," "Important," and "Remember" into direct rules.
- Keep independent requirements separate when combining them would make conditions or precedence harder to parse.
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: 471k | 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 |