Source
Relevant source takeaways
The article frames agent skills as a progressive-disclosure mechanism:
description frontmatter is the matcher signal, so it must name concrete triggers, file types, and user phrases.SKILL.md should stay compact because invoked skill content remains in context; long examples, scripts, references, and templates should live in supporting files loaded only on demand.- Process skills work best when they name stages, entry conditions, actions, done conditions, loops, and skip/shortcut rules.
- A practical habit from the source: every new project gets a project/domain skill on day one, so recurring domain knowledge is available as reusable context instead of being rediscovered in every session.
Repo evidence
MAP already covers several of the article's ideas:
docs/SKILL-EVAL.md documents skill-eval, including description-frontmatter tuning as the matching signal.src/mapify_cli/templates_src/skills/README.md.jinja classifies skills as reference, task, or hybrid, and tells authors to keep SKILL.md focused while moving long examples/troubleshooting/templates into supporting files.tests/test_skills.py validates frontmatter, Use when, Do NOT use, supported fields, skill-rules metadata, and supporting-file links.README.md describes Skill IR audit checks for hashes, unsupported frontmatter, missing supporting-file links, and injection-like instructions.docs/improvement-plan.md already tracks further compact-body linting for task workflows under 2604.033-3./map-learn captures reusable lessons after a completed workflow into learned rules, but its current contract is post-workflow learning, not a day-one project/domain skill bootstrap.
Existing issue search
Checked open and closed issues with:
gh issue list --state all --limit 120 --search "domain skill OR project domain skill OR project-specific skill OR scaffold skill OR bootstrap skill OR day one skill OR tribal knowledge"gh issue list --state all --limit 120 --search "progressive disclosure OR supporting files OR skill body compact OR SKILL.md compact OR skill lifecycle OR invoked skill content"gh issue list --state all --limit 120 --search "skill-rules OR runtimeEffects OR SkillIR OR skill metadata OR trigger description OR skill-eval OR description optimizer"gh issue list --state all --limit 120 --json number,title,state,url
No duplicate issue was found for day-one project/domain skill bootstrapping. Related prior work covers prompt-pattern catalogs and skill lifecycle hygiene, but not this onboarding slice.
Why not already covered
/map-learn is intentionally retrospective: it requires a completed workflow summary, validations, and outputs before writing reusable learned rules. That is useful after the system has already encountered project-specific friction.
The source suggests a different moment: create a domain skill at project start, before the first substantial workflow, so stable project facts, glossary, boundaries, commands, and ownership rules are available through the same skill-matching path as MAP's built-in workflows.
Problem
New MAP installations do not have a first-class way to scaffold a project-specific reference skill during onboarding. Users can manually create one, and /map-learn can accumulate lessons later, but there is no guided, conservative bootstrap path that turns initial project context into a reusable domain skill without mixing it into global MAP templates.
This leaves a gap for teams where the first few sessions repeatedly rediscover the same project-specific facts: repo layout, domain terms, safety boundaries, test commands, generated-file rules, and common workflows.
Proposed slice
Add a conservative project-domain skill bootstrap path, for example one of:
mapify init --domain-skillmapify domain-skill init- a documented
/map-domain or /map-learn --bootstrap flow if that fits the existing surface better
The generated artifact should be a project-local reference skill, not a task workflow. It should be explicit that this is user/project-owned context, not a generated MAP core skill.
Possible generated content:
- YAML frontmatter with concrete matcher triggers such as repo name, domain terms, main file types, and common user phrases.
- Short
SKILL.md sections for project purpose, repo layout, glossary, safe commands, generated-file boundaries, and when to read deeper references.
- Optional supporting files for longer architecture excerpts or command inventories.
- Provenance comments or citations when facts are discovered from repo docs.
- A clear placeholder mode when facts are unknown instead of inventing them.
Acceptance criteria
- A new-project bootstrap path can create a project-local domain/reference skill without hand-editing MAP's shipped generated templates directly.
- The skill is registered or documented so the target agent can discover it consistently.
- The scaffold keeps
SKILL.md compact and moves longer material into supporting files where appropriate.
- The scaffold does not fabricate domain facts: discovered facts must be tied to local files, or left as placeholders for the user to fill.
- The flow avoids secrets and excludes
.env*, credentials, tokens, private keys, and similar sensitive files.
- Tests cover both a minimal empty project/docs-missing path and a docs-present path.
- Documentation explains how this differs from
/map-learn: bootstrap is day-one/domain context; /map-learn is post-workflow reusable lessons.
Guardrails
- Do not make this mandatory for every
mapify init; it should be opt-in or clearly skippable.
- Do not overwrite user-edited project-domain skills on subsequent
mapify init runs.
- Do not turn this into a broad RAG/indexing feature; keep the first slice to a simple, inspectable skill scaffold.
- Preserve provider parity or explicitly document any provider-specific limitations.
- Keep generated MAP template invariants intact: edit
src/mapify_cli/templates_src/**/*.jinja for shipped changes and re-render generated trees when implementation touches templates.
Source
/Users/azalio/Downloads/Telegram Desktop/agent_skills_explained_the_folder_that_made_my_ai_agent_smarter_.mdRelevant source takeaways
The article frames agent skills as a progressive-disclosure mechanism:
descriptionfrontmatter is the matcher signal, so it must name concrete triggers, file types, and user phrases.SKILL.mdshould stay compact because invoked skill content remains in context; long examples, scripts, references, and templates should live in supporting files loaded only on demand.Repo evidence
MAP already covers several of the article's ideas:
docs/SKILL-EVAL.mddocumentsskill-eval, including description-frontmatter tuning as the matching signal.src/mapify_cli/templates_src/skills/README.md.jinjaclassifies skills asreference,task, orhybrid, and tells authors to keepSKILL.mdfocused while moving long examples/troubleshooting/templates into supporting files.tests/test_skills.pyvalidates frontmatter,Use when,Do NOT use, supported fields, skill-rules metadata, and supporting-file links.README.mddescribes Skill IR audit checks for hashes, unsupported frontmatter, missing supporting-file links, and injection-like instructions.docs/improvement-plan.mdalready tracks further compact-body linting for task workflows under2604.033-3./map-learncaptures reusable lessons after a completed workflow into learned rules, but its current contract is post-workflow learning, not a day-one project/domain skill bootstrap.Existing issue search
Checked open and closed issues with:
gh issue list --state all --limit 120 --search "domain skill OR project domain skill OR project-specific skill OR scaffold skill OR bootstrap skill OR day one skill OR tribal knowledge"gh issue list --state all --limit 120 --search "progressive disclosure OR supporting files OR skill body compact OR SKILL.md compact OR skill lifecycle OR invoked skill content"gh issue list --state all --limit 120 --search "skill-rules OR runtimeEffects OR SkillIR OR skill metadata OR trigger description OR skill-eval OR description optimizer"gh issue list --state all --limit 120 --json number,title,state,urlNo duplicate issue was found for day-one project/domain skill bootstrapping. Related prior work covers prompt-pattern catalogs and skill lifecycle hygiene, but not this onboarding slice.
Why not already covered
/map-learnis intentionally retrospective: it requires a completed workflow summary, validations, and outputs before writing reusable learned rules. That is useful after the system has already encountered project-specific friction.The source suggests a different moment: create a domain skill at project start, before the first substantial workflow, so stable project facts, glossary, boundaries, commands, and ownership rules are available through the same skill-matching path as MAP's built-in workflows.
Problem
New MAP installations do not have a first-class way to scaffold a project-specific reference skill during onboarding. Users can manually create one, and
/map-learncan accumulate lessons later, but there is no guided, conservative bootstrap path that turns initial project context into a reusable domain skill without mixing it into global MAP templates.This leaves a gap for teams where the first few sessions repeatedly rediscover the same project-specific facts: repo layout, domain terms, safety boundaries, test commands, generated-file rules, and common workflows.
Proposed slice
Add a conservative project-domain skill bootstrap path, for example one of:
mapify init --domain-skillmapify domain-skill init/map-domainor/map-learn --bootstrapflow if that fits the existing surface betterThe generated artifact should be a project-local
referenceskill, not a task workflow. It should be explicit that this is user/project-owned context, not a generated MAP core skill.Possible generated content:
SKILL.mdsections for project purpose, repo layout, glossary, safe commands, generated-file boundaries, and when to read deeper references.Acceptance criteria
SKILL.mdcompact and moves longer material into supporting files where appropriate..env*, credentials, tokens, private keys, and similar sensitive files./map-learn: bootstrap is day-one/domain context;/map-learnis post-workflow reusable lessons.Guardrails
mapify init; it should be opt-in or clearly skippable.mapify initruns.src/mapify_cli/templates_src/**/*.jinjafor shipped changes and re-render generated trees when implementation touches templates.