narrative-skills-marketplace
AGENTS.md9 starsChanged 52 days agoMITView on GitHub
An agent skills marketplace. Plugins live under plugins/; each plugin contains one or more skills under plugins/<plugin>/skills/. Skills follow the Agent Skills spec; the bash setup installer currently targets Claude Code. Authoring a skill? docs/authoring-skills.md is the canonical guide — frontmatter contract, description writing, phased body structure, progressive disclosure, composition, the template / snippet system, and CI checks. The notes below are the 60-second tour. Two scheduled Claude jobs maintain this repo (both on Opus 5.5 via anthropics/claude-code-action): - audit-weekly.yml…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- audit-repoSkill
- burndown-issuesSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 89
Never use adjective-noun (/new-lead) or noun-noun (/campaign-brief).
- Distinctive: line 93
Every skill file starts with YAML frontmatter:
- Very specific: line 178
Create snippets/<name>.md (repo-shared) or plugins/<plugin>/_snippets/<name>.md (plugin-local.
- Very specific: line 189
Run bun run gen:skill-docs to regenerate the rendered SKILL.md.
- Very specific: line 196
Write scripts/resolvers/<name>.ts exporting a ResolverFn.
- Very specific: line 198
Use {{YOUR_NAME}} or {{YOUR_NAME:arg}} in any template.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
narrative-skills-marketplace
An agent skills marketplace. Plugins live under plugins/; each
plugin contains one or more skills under plugins/<plugin>/skills/.
Skills follow the Agent Skills spec; the
bash setup installer currently targets Claude Code.
Authoring a skill?
docs/authoring-skills.mdis the canonical guide — frontmatter contract, description writing, phased body structure, progressive disclosure, composition, the template / snippet system, and CI checks. The notes below are the 60-second tour.
Commands
bash setup # register the marketplace + install every pluginProject structure
narrative-skills-marketplace/
├── .claude-plugin/
│ └── marketplace.json # Marketplace catalog (this repo)
├── plugins/
│ └── <plugin>/
│ ├── .claude-plugin/
│ │ └── plugin.json # Plugin manifest (name, version, mcpServers)
│ ├── _snippets/ # (optional) plugin-local snippets
│ └── skills/
│ └── <skill>/
│ ├── SKILL.md.tmpl # Template (source of truth, optional)
│ └── SKILL.md # Rendered file (auto-generated if .tmpl exists)
├── snippets/ # Shared snippets reused across skills
├── scripts/
│ ├── gen-skill-docs.ts # Renders SKILL.md from SKILL.md.tmpl
│ ├── discover-skills.ts
│ ├── frontmatter.ts
│ └── resolvers/ # {{PLACEHOLDER}} resolver registry
├── package.json # bun run gen:skill-docs
├── setup
└── README.mdRepo automation
Two scheduled Claude jobs maintain this repo (both on Opus 5.5 via
anthropics/claude-code-action):
audit-weekly.yml(Mon 12:00 UTC) runs/audit-repo: grades one rubric from.claude/audit-rubrics/(skills → tooling → automation, by ISO week) and files 0–5repo-auditissues. It never edits files. Close an issue as not planned to decline it for good.issue-burndown.yml(daily 13:00 UTC) runs/burndown-issues: picks one open issue, fixes it, and opens a PR for human review. It never merges. The queue is built first bybun run screen:issues, which drops issues from outside the org (unless labelledauto-fix-ok) and screens the rest for prompt injection with TypeSafe's Jev model. Addauto-fix-skipto keep an issue away from it.
Setup: repo variables ANTHROPIC_FEDERATION_RULE_ID and AUTOMATION_APP_ID,
secrets AUTOMATION_APP_PRIVATE_KEY and TYPESAFE_API_KEY. Each workflow's
preflight step names anything missing.
Naming conventions
Skills follow the verb-noun pattern (/triage-lead, /create-deck).
Single-word names are fine when the verb is unambiguous (/commit,
/qualify). Skill directory names match the slash command (lowercase,
hyphen-separated).
| Verb | When to use |
write | Long-form prose (/write-blog, /write-story) |
create | Structured artifacts (/create-slide, /create-pr) |
triage | Categorize + prioritize inbound items |
review | Evaluate existing content |
start | Begin a workflow |
capture | Persist an external artifact |
find | Search existing material |
prep | Prepare for a specific event |
build | Assemble multi-artifact output |
sweep | Scheduled hygiene pass |
register | Attach an existing external object to the platform |
Never use adjective-noun (/new-lead) or noun-noun (/campaign-brief).
SKILL.md format
Every skill file starts with YAML frontmatter:
---
name: my-skill
version: 1.0.0
description: |
One- or two-sentence description.
Include trigger phrases: "use when X", "use when Y".
allowed-tools:
- Bash
- Read
- Write
- AskUserQuestion
---- name matches the slash command (no leading
/). - allowed-tools lists every non-MCP tool the skill calls.
AskUserQuestionis required for interactive skills. MCP tools declared inplugin.jsonare globally available and do not need to be listed. - The body is a phased, interactive workflow. Number phases sequentially (Phase 1, Phase 2, …).
Skill design principles
- Interactive, not reference — walk the user through decisions; don't just display docs.
- AI does the grunt work — research, enrichment, drafting. Humans approve.
- One question at a time — never batch multiple
AskUserQuestions. - Evidence over assumptions — never skip to conclusions without data.
- Drafts, not actions — for external-facing output (email, Slack), always draft and require explicit approval before sending.
- Graceful degradation — if an MCP tool isn't available, continue without it and note manual follow-ups.
- DRY via templates — pull shared boilerplate (company-context
pinning, harness fallbacks, voice guidelines) out into
snippets/and reference it from aSKILL.md.tmplinstead of duplicating prose across skills.
Template system
Skills can be authored as a SKILL.md.tmpl with {{PLACEHOLDER}}
substitutions; bun run gen:skill-docs (also invoked by bash setup)
renders them to SKILL.md in place. Plain SKILL.md files with no
template are left untouched.
Placeholder syntax
{{RESOLVER}} # no-arg resolver
{{RESOLVER:arg1}} # one arg
{{RESOLVER:arg1:arg2}} # colon-separated argsResolver names are UPPERCASE_WITH_UNDERSCORES. Unknown resolvers fail
the render. Snippets that themselves contain {{...}} are resolved
transitively (up to 5 passes).
Placeholders only resolve through
.tmplrendering.bun run gen:skill-docsonly discovers and renders*.tmplfiles. A{{SNIPPET:...}}(or any{{...}}) sitting in a plain.mdthat the renderer never processes is shipped verbatim — it will not resolve. So a placeholder is only effective when it lives in a.tmplfile or inside a snippet that gets inlined into one.Snippet source files are the one deliberate exception, and they must stay
.md: the resolver looks them up as<name>.md, so renaming a snippet to.tmplmakes it un-findable. A snippet may nest{{SNIPPET:...}}— those resolve only because the snippet is inlined into a.tmplSKILL/reference, where the renderer's transitive passes pick them up. Never put a{{...}}placeholder in a hand-maintained.mdreference (e.g.references/FOO.md); make itreferences/FOO.md.tmplinstead.
Built-in resolvers
| Placeholder | What it does |
{{SNIPPET:<name>}} | Inlines snippets/<name>.md (or plugins/<plugin>/_snippets/<name>.md if the snippet is plugin-local). |
Adding a snippet
- Create
snippets/<name>.md(repo-shared) orplugins/<plugin>/_snippets/<name>.md(plugin-local; takes precedence). Write the markdown chunk verbatim, no frontmatter. Reference it from a template:
### Phase 2. Pin the company / context {{SNIPPET:pin-company-context}}- Run
bun run gen:skill-docsto regenerate the renderedSKILL.md.
Adding a resolver
For dynamic content (computed bash blocks, programmatic lookups, etc.) that can't be expressed as a static snippet:
- Write
scripts/resolvers/<name>.tsexporting aResolverFn. - Register it in
scripts/resolvers/index.ts. - Use
{{YOUR_NAME}}or{{YOUR_NAME:arg}}in any template.
The resolver signature is (ctx: TemplateContext, args?: string[]) => string.
ctx provides the skill name, template path, and repo root.
Generated files
Rendered SKILL.md files start with an <!-- AUTO-GENERATED ... -->
banner immediately after the frontmatter. Edit the .tmpl, never the
rendered output. bun run check:skill-docs is a --dry-run check
suitable for CI.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

